Skip to content

docs CI: fix gh-pages deploy (GITHUB_TOKEN write permissions, drop broken DOCUMENTER_KEY)#875

Merged
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:fix-docs-deploy-permissions
Jun 21, 2026
Merged

docs CI: fix gh-pages deploy (GITHUB_TOKEN write permissions, drop broken DOCUMENTER_KEY)#875
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:fix-docs-deploy-permissions

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor

Problem

The Documentation workflow's docs build passes, but the deploydocs gh-pages push fails. Two compounding causes:

  1. The build-and-deploy job had no permissions: block, so the GITHUB_TOKEN flowing into the job is read-only and cannot push to gh-pages.
  2. The build step injected DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}. When that env var is present, Documenter's deploydocs takes the SSH deploy path (git@github.com:...), which fails with Permission denied (publickey) because the deploy key is missing/invalid.

Fix (YAML-only)

  • Add a permissions: block to the build-and-deploy job:
    permissions:
      actions: write
      contents: write
      statuses: write
    This mirrors the proven pattern from SciML/OrdinaryDiffEqOperatorSplitting.jl Update optimize! method for LeastSquaresOptim case #90.
  • Remove DOCUMENTER_KEY from the build step's env. With no DOCUMENTER_KEY present, deploydocs auto-falls back to pushing over HTTPS using GITHUB_TOKEN, which the new contents: write permission now authorizes. GITHUB_TOKEN is retained in the env. No secret is required.

deploydocs(repo = "github.com/SciML/DiffEqDocs.jl.git") in docs/make.jl is already the HTTPS form, so the token path works as-is.

Verification

YAML validated with python3 (yaml.safe_load) — parses cleanly; permissions resolves 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 to master), 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

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>
@ChrisRackauckas ChrisRackauckas marked this pull request as ready for review June 21, 2026 01:35
@ChrisRackauckas ChrisRackauckas merged commit 96e8ba2 into SciML:master Jun 21, 2026
7 checks passed
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