docs CI: fix gh-pages deploy (GITHUB_TOKEN write permissions, drop broken DOCUMENTER_KEY)#875
Merged
ChrisRackauckas merged 1 commit intoJun 21, 2026
Conversation
The Documentation workflow build passes but the deploydocs gh-pages push
fails. The job injected DOCUMENTER_KEY, forcing Documenter onto the SSH
deploy path (git@github.com), which fails with "Permission denied
(publickey)" because the key is missing/invalid. The job also lacked a
permissions: block, leaving GITHUB_TOKEN read-only and unable to push.
Fix:
- Add permissions: { actions: write, contents: write, statuses: write }
to the build-and-deploy job (mirrors the proven SciML
OrdinaryDiffEqOperatorSplitting.jl SciML#90 pattern).
- Drop the DOCUMENTER_KEY env from the build step. With no DOCUMENTER_KEY
present, Documenter's deploydocs auto-uses GITHUB_TOKEN over HTTPS,
which the contents: write permission now authorizes to push gh-pages.
No secret required.
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
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
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.
Problem
The
Documentationworkflow's docs build passes, but thedeploydocsgh-pages push fails. Two compounding causes:build-and-deployjob had nopermissions:block, so theGITHUB_TOKENflowing into the job is read-only and cannot push togh-pages.DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}. When that env var is present, Documenter'sdeploydocstakes the SSH deploy path (git@github.com:...), which fails withPermission denied (publickey)because the deploy key is missing/invalid.Fix (YAML-only)
permissions:block to thebuild-and-deployjob:DOCUMENTER_KEYfrom the build step'senv. With noDOCUMENTER_KEYpresent,deploydocsauto-falls back to pushing over HTTPS usingGITHUB_TOKEN, which the newcontents: writepermission now authorizes.GITHUB_TOKENis retained in the env. No secret is required.deploydocs(repo = "github.com/SciML/DiffEqDocs.jl.git")indocs/make.jlis already the HTTPS form, so the token path works as-is.Verification
YAML validated with
python3(yaml.safe_load) — parses cleanly;permissionsresolves to{actions: write, contents: write, statuses: write}. The full deploy cannot be verified without a CI run (it requires the self-hosted runner + a push tomaster), but the change matches the proven #90 pattern and the documented Documenter token-deploy fallback.This does not disable the docs check or set
warnonly.Please ignore until reviewed by @ChrisRackauckas