Skip to content

Fix docs deploy: grant contents: write so gh-pages push succeeds#39

Closed
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:mainfrom
ChrisRackauckas-Claude:fix-docs-deploy-permissions
Closed

Fix docs deploy: grant contents: write so gh-pages push succeeds#39
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:mainfrom
ChrisRackauckas-Claude:fix-docs-deploy-permissions

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor

Problem

The only failing check on main is Documentation / Build and Deploy Documentation. The docs build succeeds — the failure is the final deploy step:

fatal: unable to access 'https://github.com/SciML/SymbolicLimits.jl.git/': The requested URL returned error: 403
Error: Failed to push:
   failed process: Process(`git push -q upstream HEAD:gh-pages`) ... ProcessExited(128)

Root cause

Commit fb8ffe7 ("Migrate CI to centralized SciML reusable workflows") replaced the old in-CI.yml docs job with a caller of SciML/.github/.github/workflows/documentation.yml@v1.

The old docs job carried:

permissions:
  contents: write
  statuses: write

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's GITHUB_TOKEN defaults to read-only. This repo has no DOCUMENTER_KEY SSH secret (the job log shows DOCUMENTER_KEY: empty and Deploying: ✔ via GITHUB_TOKEN), so Documenter deploys over HTTPS with the token — and a read-only token cannot push to gh-pages → HTTP 403.

(Repos like LinearSolve.jl use the identical caller and deploy green because they have a DOCUMENTER_KEY secret, which bypasses GITHUB_TOKEN push 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's GITHUB_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.jl exits 0 — doctests pass, document checks pass, HTML renders.
  • deploydocs correctly 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

…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>
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor Author

Superseded by SciML/.github#102.

This PR's only substantive change is adding a permissions: { contents: write, statuses: write } block to this repo's .github/workflows/Documentation.yml so the reusable workflow's GITHUB_TOKEN can push to gh-pages.

SciML/.github#102 (now merged) fixes this at the source: it sets permissions: { actions: write, contents: write, statuses: write } directly in the centralized reusable workflow .github/.github/workflows/documentation.yml. That grant is a superset of what this PR adds, and it applies to every consumer caller job — so the per-repo block here is no longer needed.

This repo's Documentation.yml consumes the reusable via uses: SciML/.github/.github/workflows/documentation.yml@v1. The v1 tag has already been retagged to include #102 (it now points at a commit whose history contains the #102 merge), so the central permission grant is already live for this repo on v1. No further action is required here.

Closing in favor of the central fix rather than merging a redundant per-repo override.

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