Skip to content

ci(docs-site): publish the documentation site to GitHub Pages from main (ITL-1170) - #429

Merged
eywalker merged 1 commit into
mainfrom
eywalker/itl-1170-docs-site-deploy
Nov 17, 2026
Merged

eywalker merged 1 commit into
mainfrom
eywalker/itl-1170-docs-site-deploy

Conversation

@eywalker

Copy link
Copy Markdown
Contributor

Closes ITL-1170 (follow-up to #425: publishing).

What this does

  • Deploy job. .github/workflows/docs-site.yml gains a deploy job (actions/deploy-pages v5.0.1, pinned by SHA) with needs: build, environment: github-pages (its url is the deployment's page_url), and job-level permissions: pages: write, id-token: write. The workflow default stays contents: read.
  • When it runs. On a push to main and on a manual run (workflow_dispatch) from main, in metamorphic-labs/orcapod-python only. It never runs on a pull request, from another branch or in a fork. On this PR the build runs and deploy is skipped.
  • Upload only when deploying. The build job uploads site/dist as the Pages artifact (actions/upload-pages-artifact v5.0.0, pinned by SHA) only when it meets the deploy job's condition.
  • No races. The deploy job is in the concurrency group docs-site-pages with cancel-in-progress: false. The workflow-level group now cancels an older run only on a pull request, so a running build or deploy on main is never cancelled.
  • The address stays in the variables. actions/configure-pages is not used. DOCS_SITE_URL / DOCS_SITE_BASE (repository variables; defaults below) remain the one source of the site's address.
  • "Development version" banner. Every page shows: "This site documents the development version of Orcapod (the main branch), 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.
  • Docs. site/README.md (CI and publishing, and how a custom domain is set), the "Documentation site" section of CLAUDE.md and .zed/rules (same text), and changelog.d/ITL-1170.md. That fragment is still unreleased on main, so this PR edits it instead of adding a second one. RELEASING.md does not mention the site and is unchanged: the site deploys from main, not on release.

What the developer must have set

  1. Settings > Pages > Build and deployment > Source = GitHub Actions. Pages was not enabled on the repository when this PR was written (the Pages API returned 404).
  2. The github-pages environment. GitHub creates it when Pages is set to deploy from GitHub Actions. Its default deployment branch rule allows the default branch, so main can deploy. Please confirm in Settings > Environments > github-pages that main is allowed. A rule that excludes main makes the deploy job fail with a "not allowed to deploy" error.
  3. Variables: nothing. With DOCS_SITE_URL and DOCS_SITE_BASE unset, 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 (or gh workflow run docs-site.yml --ref main). The merge's own push to main also 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> and DOCS_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 no CNAME file.

Checks

  • Ruff, ruff format and basedpyright are clean; there is no Python change. scripts/assemble_changelog.py --check passes, and so do tests/test_docs/test_site_content.py and tests/test_changelog_fragments.py.
  • No local pnpm build. The site build on this PR builds the banner middleware.

🤖 Generated with Claude Code

…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>
@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Warning

Review limit reached

  • Run on-demand review

This review includes 7 billable files and costs up to $1.75.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

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.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 108 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 7c8c5ef and 3ae06b7.

Files selected for processing: 7

  • .github/workflows/docs-site.yml
  • .zed/rules
  • CLAUDE.md
  • changelog.d/ITL-1170.md
  • site/README.md
  • site/astro.config.mjs
  • site/src/routeData.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@eywalker
eywalker requested a balanced review from Copilot November 17, 2026 19:49
@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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 main in 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

@eywalker
eywalker merged commit e5c223a into main Nov 17, 2026
17 checks passed
@eywalker
eywalker deleted the eywalker/itl-1170-docs-site-deploy branch November 17, 2026 19:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants