Pages currently serves main /docs directly, which publishes whatever is
committed with no check between the push and the live site. This builds the
page from src/, asserts the committed bundle matches it, and asserts the page
still loads nothing from the network — then uploads. A stale or
network-dependent page fails the job instead of going live.
Shape is GitHub's own starter pairing: configure-pages@v5,
upload-pages-artifact@v3, deploy-pages@v5, verified to exist at those tags.
Deploy is a separate job with the pages/id-token permissions scoped to it.
`cancel-in-progress: false`, because a half-published site is worse than a
stale one — pushes queue rather than interrupt a deploy already going out.
Triggered on docs/ rather than src/: docs/ carries the generated bundle, so a
src/ change only reaches the site once it has been rebuilt into docs/, which
is what the CI sync check already enforces.
Needs a one-time setting before it can work: Settings → Pages → Source must
be "GitHub Actions" rather than "Deploy from a branch". Until then the deploy
job fails on permissions. That switch needs administration:write, which
GITHUB_TOKEN does not have, so it cannot be made from CI. It is reversible —
setting Source back to a branch restores the current behaviour.
actionlint clean across all four workflows; the build job's steps were run
locally in order and pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
Claude
60cb8303ed