Fix docs deploy: grant contents: write so gh-pages push succeeds#39
Fix docs deploy: grant contents: write so gh-pages push succeeds#39ChrisRackauckas-Claude wants to merge 1 commit into
Conversation
…cceeds The migration to the centralized reusable docs workflow (SciML/.github/.github/workflows/documentation.yml@v1) dropped the permissions block that the previous in-CI.yml docs job carried (contents: write, statuses: write). The reusable workflow itself declares no permissions, so the caller token defaults to read-only. This repo has no DOCUMENTER_KEY SSH secret, so Documenter deploys via GITHUB_TOKEN. With a read-only token, the final `git push upstream HEAD:gh-pages` fails with HTTP 403 even though the docs build succeeds (gh-pages last deployed fine pre-migration from CI.yml). Restoring contents: write (plus statuses: write) on the caller propagates to the reusable workflow's GITHUB_TOKEN and restores the working deploy. Verified locally on Julia 1.12.6: docs/make.jl builds with exit 0 (doctests pass, HTML renders); deploydocs correctly skips push off-CI. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Superseded by SciML/.github#102. This PR's only substantive change is adding a SciML/.github#102 (now merged) fixes this at the source: it sets This repo's Closing in favor of the central fix rather than merging a redundant per-repo override. |
Problem
The only failing check on
mainis Documentation / Build and Deploy Documentation. The docs build succeeds — the failure is the final deploy step:Root cause
Commit
fb8ffe7("Migrate CI to centralized SciML reusable workflows") replaced the old in-CI.ymldocs job with a caller ofSciML/.github/.github/workflows/documentation.yml@v1.The old docs job carried:
and deployed successfully via
GITHUB_TOKEN(gh-pages last updated fine pre-migration, "build based on 0ff0262").The new caller declared no
permissions:block, and the reusable workflow itself declares none either, so the caller'sGITHUB_TOKENdefaults to read-only. This repo has noDOCUMENTER_KEYSSH secret (the job log showsDOCUMENTER_KEY:empty andDeploying: ✔viaGITHUB_TOKEN), so Documenter deploys over HTTPS with the token — and a read-only token cannot push togh-pages→ HTTP 403.(Repos like LinearSolve.jl use the identical caller and deploy green because they have a
DOCUMENTER_KEYsecret, which bypassesGITHUB_TOKENpush permissions.)Fix
Restore
permissions: contents: write(+statuses: write) on the caller workflow — exactly what the pre-migration docs job had. Caller permissions propagate to the reusable workflow'sGITHUB_TOKEN, restoring the working token-based deploy without requiring a secret.Verification
Built locally on Julia 1.12.6 (the version CI used):
julia --project=docs docs/make.jlexits 0 — doctests pass, document checks pass, HTML renders.deploydocscorrectly skips deployment off-CI ("could not auto-detect the building environment"), confirming the build path is healthy and only the CI deploy push was failing.The 403 is a CI-only token-permission issue not reproducible locally; this change targets exactly that.
Please ignore until reviewed by @ChrisRackauckas