ci: deploy docs via official GitHub Pages actions#559
Open
einarwar wants to merge 1 commit into
Open
Conversation
There was a problem hiding this comment.
Pull request overview
This PR modernizes the documentation deployment workflow by replacing the manual gh-pages branch force-push approach with GitHub’s official Pages actions-based pipeline, aligning the repo with OIDC-based deployments and GitHub-managed Pages history/environments.
Changes:
- Replaces the
git init+ force-push flow withactions/configure-pages,actions/upload-pages-artifact, andactions/deploy-pages. - Splits the workflow into separate
buildanddeployjobs and targets thegithub-pagesenvironment with the deployment URL. - Adds Pages-specific concurrency serialization, enables
uvcaching, and adds job timeouts.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Replace the hand-rolled 'git init + force push to gh-pages' approach with the officially supported actions/configure-pages, actions/upload-pages-artifact and actions/deploy-pages. This relies on OIDC for authentication (no GITHUB_TOKEN write scope on contents needed) and removes the force-pushed branch. Also: - Enable uv cache (enable-cache: true) for a faster build job. - Add a 'pages' concurrency group with cancel-in-progress: false so Pages deployments are serialised but never interrupted. - Add timeout-minutes safety nets to each job. - Drop the now-unused GITHUB_PAGES_BRANCH env var. NOTE: This requires the repository's Pages source to be set to 'GitHub Actions' (Settings -> Pages -> Build and deployment -> Source).
einarwar
force-pushed
the
chore/ci-publish-docs-use-official-pages-actions
branch
from
19f4dea to
edd7e20
Compare
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
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.
Replace the hand-rolled
git init+ force-push-to-gh-pagesapproach inpublish-docs.yamlwith the officially supportedactions/configure-pages,actions/upload-pages-artifactandactions/deploy-pages.Why
contents: writescope onGITHUB_TOKENis needed for docs anymore.gh-pagesbranch to maintain.github-pagesenvironment, which gives you protection rules, a clean deploy history, and surfaces the deployment URL in the Actions run UI viaenvironment.url(note: this is not exposed as a programmatic workflow output — nothing currently consumes it, so aworkflow_calloutput isn't worth adding).Other small cleanups in the same file (items 15 + a couple of bonus fixes)
permissions:block:contents: read,pages: write,id-token: write— required byactions/deploy-pages.setup-uvnow usesenable-cache: true, matching the other workflows.pagesconcurrency group withcancel-in-progress: falseso Pages deploys are serialised but never interrupted mid-deploy.timeout-minutessafety nets on both jobs.GITHUB_PAGES_BRANCHenv var.The repository's Pages source must be switched to "GitHub Actions":
Settings → Pages → Build and deployment → Source → GitHub Actions.
While the source is still set to "Deploy from a branch",
actions/deploy-pageswill fail. Once switched, the existinggh-pagesbranch can be deleted (optional cleanup).Interaction with other open PRs
permissions: contents: writeto thedocsjob inon-push-main-branch.yaml. After both PRs land, that needs to becomepages: write, id-token: write, contents: readinstead. Whichever PR merges second will need a trivial rebase — I'll do that follow-up.