Repository navigation
ci(docs-site): publish the documentation site to GitHub Pages from main (ITL-1170) - #429
Conversation
…in (ITL-1170) The docs-site workflow gains a deploy job (actions/deploy-pages, pinned by SHA) that runs after the build on a push to main and on a manual run from main, in metamorphic-labs/orcapod-python only, never on a pull request. Only a run that deploys uploads site/dist as the Pages artifact (actions/upload-pages-artifact). The deploy job grants itself pages: write and id-token: write; the workflow default stays contents: read. Deploys never race (concurrency group docs-site-pages) and a running build or deploy on main is never cancelled. Every page shows a banner saying the site documents the development version (main), with links to PyPI and the changelog instead of a release number (site/src/routeData.ts, a Starlight route middleware). site/README, CLAUDE.md and .zed/rules describe publishing, the manual run and how a custom domain is set; the ITL-1170 changelog fragment says the site is published. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Warning Review limit reached
This review includes 7 billable files and costs up to $1.75.
Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing. Or wait 14 minutes for your next included review. View limit details
|
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
🟢 Approval recommended
The review reports no active issues with the documentation publishing changes.
No open issues 🎉
What changed in this PR
Adds GitHub Pages publishing to the existing Astro Starlight documentation build, completing the publishing follow-up to #425.
Changes:
- Uploads and deploys the site only on pushes or manual runs from
mainin the primary repository, with serialized deployments. - Adds a development-version banner linking to PyPI and the changelog.
- Documents publishing prerequisites and custom-domain setup, and updates contributor guidance and the changelog.
| File | Description |
|---|---|
site/src/routeData.ts |
Adds the default development-version banner. |
site/README.md |
Documents deployment behavior, setup, and custom domains. |
site/astro.config.mjs |
Registers the banner middleware. |
CLAUDE.md |
Updates publishing guidance and agent restrictions. |
changelog.d/ITL-1170.md |
Records Pages publishing and the development banner. |
.zed/rules |
Mirrors the updated publishing guidance. |
.github/workflows/docs-site.yml |
Adds conditional artifact upload and Pages deployment with concurrency controls. |
Review effort: Balanced
Closes ITL-1170 (follow-up to #425: publishing).
What this does
.github/workflows/docs-site.ymlgains adeployjob (actions/deploy-pagesv5.0.1, pinned by SHA) withneeds: build,environment: github-pages(itsurlis the deployment'spage_url), and job-levelpermissions: pages: write, id-token: write. The workflow default stayscontents: read.mainand on a manual run (workflow_dispatch) frommain, inmetamorphic-labs/orcapod-pythononly. It never runs on a pull request, from another branch or in a fork. On this PR the build runs anddeployis skipped.site/distas the Pages artifact (actions/upload-pages-artifactv5.0.0, pinned by SHA) only when it meets the deploy job's condition.docs-site-pageswithcancel-in-progress: false. The workflow-level group now cancels an older run only on a pull request, so a running build or deploy onmainis never cancelled.actions/configure-pagesis not used.DOCS_SITE_URL/DOCS_SITE_BASE(repository variables; defaults below) remain the one source of the site's address.mainbranch), which may differ from the latest release. For the releases, see PyPI and the changelog." The banner never names a release. It comes from a Starlight route middleware,site/src/routeData.ts, which sets the page banner unless a page has its own.site/README.md(CI and publishing, and how a custom domain is set), the "Documentation site" section ofCLAUDE.mdand.zed/rules(same text), andchangelog.d/ITL-1170.md. That fragment is still unreleased onmain, so this PR edits it instead of adding a second one.RELEASING.mddoes not mention the site and is unchanged: the site deploys frommain, not on release.What the developer must have set
github-pagesenvironment. GitHub creates it when Pages is set to deploy from GitHub Actions. Its default deployment branch rule allows the default branch, somaincan deploy. Please confirm in Settings > Environments > github-pages thatmainis allowed. A rule that excludesmainmakes the deploy job fail with a "not allowed to deploy" error.DOCS_SITE_URLandDOCS_SITE_BASEunset, the site is at https://metamorphic-labs.github.io/orcapod-python/.The first deploy is the developer's manual run once this PR is merged and Pages is set: Actions > Documentation site > Run workflow, branch
main(orgh workflow run docs-site.yml --ref main). The merge's own push tomainalso deploys if Pages is already set by then. No agent changes a setting, a variable or an environment, and no agent runs the deploy.Custom domain (later): set
DOCS_SITE_URL=https://<domain>andDOCS_SITE_BASE=/, set Settings > Pages > Custom domain (with the DNS record GitHub asks for), then run the deploy by hand. A site deployed by Actions needs noCNAMEfile.Checks
scripts/assemble_changelog.py --checkpasses, and so dotests/test_docs/test_site_content.pyandtests/test_changelog_fragments.py.pnpm build. The site build on this PR builds the banner middleware.🤖 Generated with Claude Code