ci(docs): build the site on pull requests, deploy only from main - #40
Merged
Conversation
docs.yml had no `pull_request` trigger — only push-to-main and workflow_dispatch. So `mkdocs build --strict` never ran before merge, and a broken in-site link passed review unnoticed and failed afterwards on the deploy: the point where a failure is most visible and least convenient, and where main is already carrying the bad link. `--strict` is only a gate if it runs before merge. Adds the pull_request trigger with the same paths filter, and keeps PRs from publishing anything: - `deploy` is gated on `github.event_name != 'pull_request'`, so a PR proves the site builds and never touches the live site. - The Pages artifact upload is gated the same way; it only feeds `deploy`. - Pages write scopes moved from the workflow down to the `deploy` job. Previously every job got `pages: write` and `id-token: write`; now a pull-request run holds `contents: read` alone and cannot publish even in principle. - Concurrency is split by event. Deploys keep the shared `pages` group and still never cancel one in flight; PR builds get a per-ref group so they neither queue behind a deploy nor hold one up, and a new push to a PR supersedes that PR's earlier build. Verified locally with the pinned toolchain (mkdocs 1.6.1 + mkdocs-material 9.7.6 in a venv): `mkdocs build --strict` exits 0 on the current tree, so this is preventive rather than fixing a break already present. Workflow YAML parsed to confirm the triggers, the two `if` gates, and the moved permissions. This PR changes .github/workflows/docs.yml, which matches the new filter, so the workflow exercises itself here: docs should run and build, and deploy should be skipped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
1 participant
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.
docs.ymlhad nopull_requesttrigger — only push-to-main andworkflow_dispatch. Somkdocs build --strictnever ran before merge.The consequence: a broken in-site link passes review unnoticed, then fails after merge on the deploy — the point where a failure is most visible and least convenient, and where
mainis already carrying the bad link.--strictis only a gate if it runs before merge.Changes
Adds the
pull_requesttrigger with the same paths filter, and keeps PRs from publishing anything:deploygated ongithub.event_name != 'pull_request'deploy, which never runs on a PR.deployjobpages: write+id-token: write. A PR run now holdscontents: readalone and cannot publish even in principle.pagesgroup and still never cancel one in flight. PR builds get a per-ref group, so they neither queue behind a deploy nor hold one up, and a new push to a PR supersedes its own earlier build.That last one matters: leaving PR builds in the shared
pagesgroup would have made every PR serialise against the deploy queue.Verification
Ran the pinned toolchain locally (
mkdocs==1.6.1+mkdocs-material==9.7.6, matching the workflow):mkdocs build --strict→ exit 0 on the current tree. This is preventive, not fixing a break already present.ifgates, and the moved permissions block.Self-demonstrating
This PR changes
.github/workflows/docs.yml, which matches the new paths filter — so the workflow exercises itself here. Expected on this PR: docs / build runs and passes, docs / deploy is skipped. Worth confirming that in the checks before merging, since it's the whole point of the change.