docs-changed #13
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # SourceBans++ docs deploy workflow (cutover deliverable for issue #1333). | |
| # | |
| # This repo is the GitHub Pages deploy target for <https://sbpp.github.io/>. | |
| # The docs source lives in `sbpp/sourcebans-pp` under `docs/` (Astro Starlight); | |
| # this workflow checks that repo out, builds the site, and publishes via | |
| # GitHub's first-party `actions/deploy-pages`. | |
| # | |
| # Triggers: | |
| # - repository_dispatch (event type: docs-changed) — fired by | |
| # `.github/workflows/docs-deploy-trigger.yml` in `sbpp/sourcebans-pp` after a | |
| # push to main that touches `docs/**`. The dispatcher authenticates with a | |
| # fine-grained PAT (`Actions: write` scope on this repo only) stored as | |
| # `secrets.DOCS_DEPLOY_PAT` over there. | |
| # - workflow_dispatch — manual button in the Actions UI for forced redeploys. | |
| # Always available; no credentials needed (runs entirely inside this repo). | |
| # - schedule (weekly Sunday) — safety net in case a dispatch is dropped, the | |
| # upstream source is unreachable at dispatch time, or a previous deploy | |
| # failed silently. | |
| # | |
| # MANUAL SETUP REQUIRED (see issue #1333 cutover steps; cannot be configured in | |
| # workflow YAML): | |
| # - Settings → Pages → Source must be set to "GitHub Actions" (UI-only). | |
| # - For automatic deploys on docs PR merges (optional — `workflow_dispatch` | |
| # and the weekly cron cover the bases otherwise): create a fine-grained PAT | |
| # scoped to `sbpp/sbpp.github.io` only with the `Actions: Read and write` | |
| # repository permission, then register it on `sbpp/sourcebans-pp` as | |
| # `secrets.DOCS_DEPLOY_PAT`. The dispatcher there picks it up; no setup | |
| # is needed in this repo. | |
| name: Deploy docs to Pages | |
| on: | |
| repository_dispatch: | |
| types: [docs-changed] | |
| workflow_dispatch: | |
| schedule: | |
| # Weekly safety net at Sunday 05:17 UTC. Non-zero minute avoids GitHub's | |
| # top-of-hour cron congestion (per their scheduled-events docs). | |
| - cron: '17 5 * * 0' | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Allow only one concurrent deployment, but never cancel an in-flight one — | |
| # Pages deploys should always finish to avoid leaving the site in a | |
| # half-published state. Standard `actions/deploy-pages` convention. | |
| # | |
| # Group name matches the issue #1333 §6 spec (`pages-deploy`) rather than | |
| # GitHub's example default (`pages`). Since this is the only workflow in | |
| # this repo that touches Pages, either choice serializes the same set of | |
| # runs — we just track the spec verbatim so the cross-repo intent is | |
| # obvious to anyone diffing the cutover. | |
| concurrency: | |
| group: pages-deploy | |
| cancel-in-progress: false | |
| jobs: | |
| build-and-deploy: | |
| # Pinned (not `ubuntu-latest`) to match sibling | |
| # `sbpp/sourcebans-pp/.github/workflows/docs-build.yml` so the build | |
| # validation gate and the deploy run on byte-identical runner images. | |
| runs-on: ubuntu-24.04 | |
| # Belt-and-suspenders against an upstream npm/Astro hang. Sibling | |
| # `docs-screenshots.yml` uses 30; the deploy is build-only (no | |
| # docker-compose / Playwright), so 15 is comfortably above the | |
| # observed steady-state runtime. | |
| timeout-minutes: 15 | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| # All `run:` steps below operate inside `docs/`. `cache-dependency-path` | |
| # and `path:` inputs to `uses:` actions stay rooted at the workspace | |
| # because action inputs are interpreted relative to the workspace, not | |
| # the job's `working-directory` default. | |
| defaults: | |
| run: | |
| working-directory: docs | |
| steps: | |
| - name: Checkout sourcebans-pp (docs source) | |
| # Precedence: dispatched runs (repository_dispatch from | |
| # `sourcebans-pp/.github/workflows/docs-deploy-trigger.yml`) | |
| # carry the source commit SHA in the client payload — pin to it | |
| # so two pushes A, B in quick succession don't race (A's deploy | |
| # would otherwise check out main and silently rebuild from B). | |
| # workflow_dispatch and schedule have no payload, so they fall | |
| # through to the floating `main` ref by design (manual reruns | |
| # and the weekly safety net both want the latest). | |
| uses: actions/checkout@v5 | |
| with: | |
| repository: sbpp/sourcebans-pp | |
| ref: ${{ github.event.client_payload.source_sha || 'main' }} | |
| - name: Setup Node | |
| uses: actions/setup-node@v5 | |
| with: | |
| # Astro requires Node >=22.12.0 (build fails on 20 with an | |
| # explicit unsupported-engine error). Keep this in lockstep | |
| # with sibling `sourcebans-pp/.github/workflows/docs-build.yml` | |
| # and the documented floor in `sourcebans-pp/docs/README.md`: | |
| # asymmetry between the validation gate and the deploy would | |
| # mean a build that passes CI could still fail here. | |
| node-version: '22' | |
| cache: 'npm' | |
| cache-dependency-path: docs/package-lock.json | |
| - name: Install dependencies | |
| run: npm ci | |
| - name: Build site | |
| run: npm run build | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v5 | |
| with: | |
| path: docs/dist | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v5 |