Skip to content

Restore contents:write permission for docs deploy (fix gh-pages 403)#52

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

Restore contents:write permission for docs deploy (fix gh-pages 403)#52
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:fix-docs-deploy-permissions

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor

Problem

The docs build passes, but the deploydocs push to gh-pages fails (403 / "Permission denied" / GITHUB_TOKEN cannot push).

Root cause

The CI-centralization migration dropped the permissions: block from the build caller job in .github/workflows/Documentation.yml. The job calls the centralized reusable SciML/.github/.github/workflows/documentation.yml@v1, which declares no permissions: of its own. In GitHub Actions, when a reusable workflow declares no permissions, the caller job's permissions flow through to the GITHUB_TOKEN it receives. With no permissions block on the caller, that token defaults to read-only and cannot push to the gh-pages branch, so the deploy step 403s while the build itself looks green.

ColPrac uses the GITHUB_TOKEN-based deploy path (no DOCUMENTER_KEY); Documenter's deploydocs auto-uses GITHUB_TOKEN when DOCUMENTER_KEY is absent, so all that is needed is to grant the caller job write access.

Fix

Add the permissions: block to the build caller job, mirroring the proven fix in OrdinaryDiffEqOperatorSplitting.jl #90:

jobs:
  build:
    permissions:
      actions: write
      contents: write
      statuses: write
    uses: "SciML/.github/.github/workflows/documentation.yml@v1"
    secrets: "inherit"

Verification

  • YAML validated locally with python3 -c "import yaml; yaml.safe_load(...)".
  • The deploy itself can only be confirmed by a CI run on master (where the token has the granted scope on PRs from a fork it is still read-only by design). The change is correct by matching the proven #90 pattern: it restores exactly the permissions a GITHUB_TOKEN-based deploydocs needs to push to gh-pages.
  • No docs check was disabled and warnonly was not set.

Please ignore until reviewed by @ChrisRackauckas

The CI-centralization migration dropped the `permissions:` block from the
`Documentation.yml` caller job. Because the reusable
`SciML/.github/.github/workflows/documentation.yml@v1` declares no
permissions of its own, the caller job's permissions flow through to the
`GITHUB_TOKEN` passed into Documenter's `deploydocs`. With no permissions
block, that token is read-only and cannot push to the `gh-pages` branch,
so the build succeeds but the deploy step fails with a 403.

Add the same `permissions` block used by the proven fix in
OrdinaryDiffEqOperatorSplitting.jl #90 (`actions: write`,
`contents: write`, `statuses: write`) so the token can push to gh-pages.

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:20
@ChrisRackauckas ChrisRackauckas merged commit 9f2bc8b into SciML:master Jun 21, 2026
4 checks passed
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor Author

Superseded by SciML/.github#102, which sets permissions: contents: write in the centralized documentation.yml reusable itself — so no per-repo permissions block is needed once v1 is retagged. Closing this in favor of the central fix.

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