Skip to content

ci: publish documentation through GitHub Pages Actions - #14

Open
beardedeagle wants to merge 2 commits into
mainfrom
docs-pages-actions
Open

beardedeagle wants to merge 2 commits into
mainfrom
docs-pages-actions

Conversation

@beardedeagle

@beardedeagle beardedeagle commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

Summary

The Docs job stops after building, leaving the published site on the old gh-pages snapshot. Upload the built book and deploy it through GitHub Pages for pushes and manual runs on main. Pull requests build and upload an artifact without deploying.

  • Pin configure-pages v6.0.0, upload-pages-artifact v5.0.0 and deploy-pages v5.0.1 to their full release commits.
  • Confine Pages write/OIDC permissions to the deploy job and preserve active main deployments when newer runs arrive.
  • Include changelog, Justfile and setup-action changes in docs triggers; update contributor guidance and the initial-release changelog.
  • Authenticate GitHub fetches only in the two Nix check steps using the existing read-only job token, preserving setup steps and file-based Nix configuration.

How was this verified?

  • actionlint .github/workflows/docs.yml passes.
  • just docs passes with the existing mdbook-mermaid version warning.
  • Release/tag checks and isolated gh actions-lock --verify pass. The released upload action's nested SHA matches the official upload-artifact v7.0.0 tag. The two unchanged local setup actions contain only run steps.
  • Required commit/push hooks pass, including 186 native tests, formatting, native/release/Linux Clippy, a locked build, Markdown lint, cargo-deny and cargo-audit.
  • Both hosted Rust jobs and both Nix jobs pass on 2656667, including native Nix builds and all-system evaluation. The preceding macOS failures stop before Postmaster compilation/tests on unauthenticated GitHub API rate limits.
  • Hosted Docs build/upload succeeds; all 56 current-head artifact files match the rebuilt local book, including Mermaid assets. PR deployment is skipped as intended. Actual main deployment and served-site verification remain post-merge checks.

Pages is configured for Actions publication, and the github-pages environment permits only main. The generated gh-pages branch is removed; its history is preserved in a verified Git bundle. The first main deployment and served-artifact verification remain after merge. Rust runtime code and Cargo dependencies are unchanged.

Checklist

  • The diff is focused -- one logical change.
  • just ci-rust passes locally.
  • All five active latest-head hosted jobs pass; dependency-policy checks also pass locally.
  • Hosted artifact upload and PR deploy denial pass; actual main publication remains a post-merge check.
  • just docs succeeds and documentation describes the resulting behavior.
  • Commit message has an imperative subject.
  • I have read the contributing guidelines.

Copilot AI balanced review requested due to automatic review settings November 10, 2026 14:43
@coldtea-pr-lens

Copy link
Copy Markdown

Note

The title starts with ci:, so PR Lens left this pull request undrawn. Comment @pr-lens draw to draw it

github.comment.notice: false in .github/pr-lens.yml turns this note off

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The cutover depends on out-of-repository Pages settings and main-only environment restrictions that require maintainer verification, along with the first hosted deployment.

No open issues 🎉

What changed in this PR

Moves documentation publishing from the existing gh-pages snapshot to GitHub Pages Actions. Pull requests build and upload the book without deploying; pushes and manual runs on main publish it.

Changes:

  • Adds commit-pinned Pages configuration, artifact upload, and deployment actions.
  • Restricts write/OIDC permissions to deployment and preserves active main-branch runs.
  • Expands documentation triggers and updates contributor guidance and the changelog.
File Description
CHANGELOG.md Records the documentation build and publishing workflow.
.github/​workflows/​docs.yml Adds artifact upload, main-only deployment, and expanded triggers.
.github/​CONTRIBUTING.md Documents hosted builds and main-only publishing behavior.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues were identified for the migration to GitHub Pages Actions.

No open issues 🎉

Review effort: Balanced

This branch has not been deployed

No deployments
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