Reset repo to deploy shell for Starlight docs migration (sourcebans-pp#1333)#54
Merged
Merged
Conversation
Issue #1333 cutover deliverable. The docs source is moving into `sbpp/sourcebans-pp` under `docs/` (Astro Starlight). This repo becomes a thin deploy target. The new workflow checks out sourcebans-pp@main, runs `npm ci && npm run build` in docs/, and publishes via GitHub's first-party deploy-pages action. Triggers: repository_dispatch (event type: docs-changed) from the sibling `docs-deploy-trigger.yml` in sourcebans-pp, workflow_dispatch for manual reruns, and a weekly Sunday cron as a safety net. Manual cutover steps required after this lands (see issue #1333): - Settings → Pages → Source must be flipped to "GitHub Actions". - The `sbpp-docs-deploy` GitHub App must exist with Actions:write on this repo, with its ID + private key registered as vars.DOCS_DEPLOY_APP_ID / secrets.DOCS_DEPLOY_APP_KEY in sourcebans-pp. This PR cannot land before the sibling sourcebans-pp PR (also part of issue #1333) — deleting the Hugo source while no Starlight source exists upstream would 404 the live site.
Issue #1333. Authoring is moving into `sbpp/sourcebans-pp` under `docs/` (Astro Starlight); this repo is now a deploy shell only. The README points contributors at the new source repo and includes a short local-preview pointer for anyone who lands here looking for the docs.
Issue #1333. The Hugo + kube-theme stack served this repo from 2018
through the 1.7.x docs. With authoring moving into
`sbpp/sourcebans-pp/docs/` (Astro Starlight), nothing in this repo
needs to be built locally anymore — the deploy workflow pulls source
from the new location at deploy time.
Removed:
- Gruntfile.js, package.json, yarn.lock — the Lunr search index
build that ran before Hugo on every deploy.
- archetypes/ — Hugo new-page templates (blog, docs, default).
- config.toml — Hugo site config (title, theme, menus, GA tag).
- content/ — 13 Hugo Markdown pages under docs/ + the FAQ index.
Same content is being ported to Starlight in the sibling
sourcebans-pp PR.
- layouts/ — Hugo layout overrides (404, baseof, list, single,
index, partials/{favicon,footer,header}).
- static/ — vendored FontAwesome bundles, brand favicons, Lato
font subset, and the master.css. The Starlight site uses its own
font stack and ships its own favicon/brand mark.
- themes/kube — the upstream Hugo theme submodule
(https://github.com/jeblister/kube), unmaintained since 2018.
- .gitmodules — only entry was themes/kube.
- .gitattributes — only rule was a Hugo-specific
`static/updater/* linguist-detectable=false`, which the static/updater
directory was already deleted by #51.
Kept:
- LICENSE — repo licence stays.
- .gitignore — generic OS/IDE ignores still useful.
- README.md — replaced in the previous commit with the deploy-shell
pointer.
- .github/workflows/deploy.yml — replaced in the first commit with
the new Pages deploy.
After this commit the working tree is exactly: LICENSE, README.md,
.gitignore, .github/workflows/deploy.yml. That's the deploy shell.
… m4, m5, m6) Five small drift fixes against the sibling docs-build.yml in sourcebans-pp so the validation gate and the deploy run in lockstep: - M1 Node 22 -> 20. Sibling docs-build.yml uses 20 and the docs README documents "Node 20 LTS or newer" as the floor; deploying on a Node major the validation gate never tested could ship a build that passes CI and still fails here. - M2 concurrency group `pages` -> `pages-deploy`. Issue #1333 §6 specifies the latter; either choice serializes the same set of runs since this is the only Pages workflow in this repo, but tracking the spec verbatim makes the cross-repo intent obvious to anyone diffing the cutover. YAML comment added explaining the choice. - m4 add `timeout-minutes: 15` on the build-and-deploy job. The sibling docs-screenshots.yml uses 30 (it boots docker compose + Playwright); deploy is build-only so 15 is comfortably above the steady-state runtime while still bounding an upstream hang. - m5 `runs-on: ubuntu-latest` -> `ubuntu-24.04`. Matches the sibling workflows so the build runs on byte-identical runner images. ubuntu-latest currently floats to 24.04 anyway, but pinning means GitHub's eventual default-bump can't silently change what we deploy. - m6 lift the per-step `working-directory: docs` to job-level `defaults.run.working-directory: docs`. Same shape the sibling docs-build.yml uses. Inputs to `uses:` actions (`cache-dependency-path: docs/package-lock.json`, `path: docs/dist`) stay rooted at the workspace because action inputs are interpreted relative to the workspace root, not the job's `working-directory` default — comment added to that effect so the asymmetry doesn't read as a bug. No functional change to triggers, permissions, or the action versions themselves; those are addressed in follow-up commits.
Two of the four pins were trailing current majors in ways that matter; bumping the other two for symmetric upgrades. - actions/upload-pages-artifact@v3 -> @v5. v3 was rolled forward to v4 in mid-2024 and to v5 in April 2026; the v5 line bundles upload-artifact@v7 (Node 24 runtime) ahead of GitHub's deprecation of Node 20 on the runner side. Staying on v3 silently relies on the deprecated upload-artifact@v4 chain and would break on the runner-side cutover. - actions/deploy-pages@v4 -> @v5. v5 (March 2026) is the Node 24 runtime version; same upcoming-deprecation calculus. - actions/checkout@v4 -> @v5 and actions/setup-node@v4 -> @v5 for symmetric upgrades. v6 lines exist for both (checkout@v6.0.2, setup-node@v6.4.0) but v6 brings credential / runtime version bumps that the rest of the org's workflows haven't adopted yet — v5 is the conservative pick that still moves us off Node-20-era pins. The sibling sourcebans-pp workflows can follow on the same cadence. No semantic change to inputs (cache-dependency-path, path, etc.) — the v5 lines are drop-in for the inputs we use.
Sibling sourcebans-pp/.github/workflows/docs-deploy-trigger.yml
already sends the source commit SHA in the repository_dispatch
client_payload (`client_payload[source_sha]=${{ github.sha }}`); the
deploy was ignoring it and always checking out the floating
`sourcebans-pp@main` ref.
Race shape that was open: two pushes A, B land on sourcebans-pp main
in quick succession. The dispatcher fires twice (its own
`docs-deploy-trigger` concurrency group serializes the dispatch step
itself, but each dispatch produces its own run here). Run A starts
the checkout step after run B has already pushed, sees `main` now
points at B, and silently rebuilds from B — meaning the build labelled
"deploying SHA A" actually deploys SHA B.
Fix: `ref: ${{ github.event.client_payload.source_sha || 'main' }}`.
- repository_dispatch path -> pins to the source SHA the dispatcher
captured at trigger time, so each run deploys exactly what the
dispatcher meant.
- workflow_dispatch path -> empty payload, falls through to `main`
(manual reruns explicitly want the latest tip).
- schedule path -> same: weekly safety-net wants the latest tip.
The fall-through default is the existing semantics, so non-dispatch
triggers behave exactly as before.
The Hugo source, package.json, yarn.lock, and themes/kube were all removed in 55ff386 — leaving the matching ignore entries (`public`, `dev`, `node_modules`) as dead lines that document a build pipeline this repo no longer has. Anyone landing here looking for "where do the build artifacts go?" would read those entries and get the wrong mental model. The remaining entries (Windows / OSX / NetBeans / Recycle Bin) are generic OS/IDE artefacts that still apply to anyone editing README.md or the deploy workflow locally; they stay.
This was referenced May 11, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue: sbpp/sourcebans-pp#1333 — cutover step 1.
Sibling PR: sbpp/sourcebans-pp#1339.
What this PR does
This is the
sbpp.github.io-side half of #1333. The repo stops being a Hugo source and becomes a thin GitHub Pages deploy shell: GitHub Actions checks out the newdocs/directory insbpp/sourcebans-pp@main, builds the Astro Starlight site, and publishes viaactions/deploy-pages.The repo has to keep its name (
sbpp.github.io) because GitHub Pages for an org requires the exact<org>.github.ioslug for the apex site; that's why this can't just be a redirect or a deletion.Commits
4029c46) — new.github/workflows/deploy.ymltriggered byrepository_dispatch(docs-changed),workflow_dispatch, and a weekly Sunday 05:17 UTC safety-net cron. Uses GitHub's first-partyactions/checkout,actions/setup-node,actions/upload-pages-artifact,actions/deploy-pages. No PAT, no force-push, no third-party deploy action.07e4a90) — verbatim text from #1333's cutover step 1, plus a short local-preview pointer.55ff386) —git rmofGruntfile.js,package.json,yarn.lock,archetypes/,config.toml,content/,layouts/,static/, thethemes/kubesubmodule (also dropped from.gitmodules), and.gitattributes. 59 files, ~9.6k deletions.LICENSEand.gitignorestay.Adversarial review pass (post-worker)
Reviewer found no blockers. All majors and all cheap minors addressed in the 4 follow-up commits below; m9 deferred per reviewer agreement.
6d04276pages→pages-deploy(match issue §6 spec)6d04276upload-pages-artifact@v3→v5,deploy-pages@v4→v5,checkout@v4→v5,setup-node@v4→v5c44af82repository_dispatchruns (race guard)262832b.gitignore0e5b474timeout-minutes: 156d04276runs-on: ubuntu-24.04(pinned, matches sibling)6d04276working-directory: docsto job-leveldefaults6d04276git clone --depth=1suggestiongit log/ blame during local preview)What's removed and why
Gruntfile.jscontent/docs/and wrotestatic/Content-Index.jsonfor client-side Lunr search.package.jsongrunt,toml) for the Gruntfile.yarn.lockarchetypes/{blog,default,docs}.mdhugo newscaffolding stubs.config.tomldocs/astro.config.mjsupstream.content/docs/*.md(12 pages) +content/faq/_index.mdsbpp/sourcebans-pp/docs/src/content/docs/.layouts/**/*.htmlkubetheme.static/css/*kubemaster stylesheet.docs/src/styles/sbpp.cssupstream.static/font/Lato-SemiboldItalic.woffstatic/img/favicons/*browserconfig.xml+site.webmanifest.favicon.svg+logo.srcupstream.static/js/fontawesome*.js(12 files, ~7k lines)themes/kube(submodule)https://github.com/jeblister/kube.git— last upstream commit 2018..gitmodules.gitattributesDeploy workflow trigger semantics
repository_dispatchdocs-changed— fired bysbpp/sourcebans-pp/.github/workflows/docs-deploy-trigger.ymlon every push tomainthat touchesdocs/**. The dispatcher mints a short-lived installation token from the org-ownedsbpp-docs-deployGitHub App (Actions:write on this repo only). The dispatch carriesclient_payload[source_sha]so the deploy job pins to the source commit, not justmain(race guard for concurrent dispatches).workflow_dispatch— manual button in the Actions UI for forced rebuilds.schedule(Sunday 05:17 UTC) — weekly safety net. The 05:17 minute (vs0) avoids GitHub's documented top-of-hour cron-tick congestion.Concurrency group
pages-deploywithcancel-in-progress: false(matches #1333 §6).Before merging (manual cutover checklist)
https://github.com/sbpp/sourcebans-pp/tree/main/docsexists and thatdocs/package-lock.jsonis committed.sbpp/sbpp.github.io: Settings → Pages → Build and deployment → Source = "GitHub Actions" (UI-only flip; not configurable from the workflow file).sbpp-docs-deployGitHub App at the org level. Permissions:Actions: writeonsbpp.github.ioonly.sbpp/sbpp.github.io.sbpp/sourcebans-pprepo settings, register:vars.DOCS_DEPLOY_APP_ID= the App's numeric IDsecrets.DOCS_DEPLOY_APP_KEY= the App's downloaded private key (full PEM)Deploy docs to Pagesvia Actions UI (workflow_dispatch) and verifyhttps://sbpp.github.io/serves the new Starlight site.masterbranch (the oldkube-rendered HTML target from when Pages was "Deploy from a branch") AND thesrcbranch (also pre-Hugo legacy) from the remote.sbpp.github.iofor ~30 days for any inbound PRs and redirect contributors tosourcebans-pp/docs/.