Summary
Remove the self-hosted DocC publishing pipeline (Doc.yml → gh-pages → GitHub Pages). It has been failing on every run for months and duplicates the documentation we already publish via the Swift Package Index (SPI). We are consolidating on SPI as the single documentation host.
Current state (broken)
- Workflow:
.github/workflows/Doc.yml (calls sersoft-gmbh/oss-common-actions/.github/workflows/swift-generate-and-publish-docs.yml@main).
- Every run fails. Last run was
2025-10-01; GitHub Pages status is errored (https://wei18.github.io/github-rest-api-swift-openapi/).
- Failure is in the reusable workflow's
spm-context job, ~25s in (before any doc generation), which then skips generate-docs, publish-docs, merge-docs.
Root cause
Doc.yml triggers only on release: [published, edited] and on pushes that touch Doc.yml itself — not on normal main commits. So documentation edits (e.g. the Issues tutorial) never trigger it.- On release tags, the
Release.yml pipeline strips the github/rest-api-description submodule at tag time (for SPM consumability). Package.swift / SPM manifest introspection then can't fully resolve in the spm-context job → fast failure.
- Net effect: the
gh-pages branch is stale and Pages is errored.
Decision
Delete this pipeline rather than fix it. Rationale:
- SPI already builds and hosts our DocC (reference docs render at
…/main/documentation/githubrestapiissues; SPI also serves tutorials at …/main/tutorials/<name>). Maintaining a second, redundant, always-failing pipeline is pure liability.
- The
README tutorial link points at SPI, not at Pages — nothing depends on the self-hosted output.
Action items
If we ever want self-hosted docs again (how to fix)
- Trigger on
push: branches: [main] (not only releases), so content edits publish.
- Build docs on a checkout that retains the submodule (or generate sources first), so
spm-context can resolve the manifest — i.e. don't reuse the tag-time submodule-stripped state.
- Given 50 targets and ~29 MB of generated Swift, budget the job accordingly (GitHub Actions allows up to 6h, unlike SPI's tighter per-build limit).
Related
- SPI-side documentation is currently stale because SPI reports 0 completed builds for this package (tracked separately, upstream issue on
SwiftPackageIndex/SwiftPackageIndex-Server).
Summary
Remove the self-hosted DocC publishing pipeline (
Doc.yml→gh-pages→ GitHub Pages). It has been failing on every run for months and duplicates the documentation we already publish via the Swift Package Index (SPI). We are consolidating on SPI as the single documentation host.Current state (broken)
.github/workflows/Doc.yml(callssersoft-gmbh/oss-common-actions/.github/workflows/swift-generate-and-publish-docs.yml@main).2025-10-01; GitHub Pages status iserrored(https://wei18.github.io/github-rest-api-swift-openapi/).spm-contextjob, ~25s in (before any doc generation), which then skipsgenerate-docs,publish-docs,merge-docs.Root cause
Doc.ymltriggers only onrelease: [published, edited]and on pushes that touchDoc.ymlitself — not on normalmaincommits. So documentation edits (e.g. the Issues tutorial) never trigger it.Release.ymlpipeline strips thegithub/rest-api-descriptionsubmodule at tag time (for SPM consumability).Package.swift/ SPM manifest introspection then can't fully resolve in thespm-contextjob → fast failure.gh-pagesbranch is stale and Pages iserrored.Decision
Delete this pipeline rather than fix it. Rationale:
…/main/documentation/githubrestapiissues; SPI also serves tutorials at…/main/tutorials/<name>). Maintaining a second, redundant, always-failing pipeline is pure liability.READMEtutorial link points at SPI, not at Pages — nothing depends on the self-hosted output.Action items
.github/workflows/Doc.yml.gh-pagesbranch.If we ever want self-hosted docs again (how to fix)
push: branches: [main](not only releases), so content edits publish.spm-contextcan resolve the manifest — i.e. don't reuse the tag-time submodule-stripped state.Related
SwiftPackageIndex/SwiftPackageIndex-Server).