From 6a8f43f6fcbbfe68238b1affe3ed405c09586a01 Mon Sep 17 00:00:00 2001
From: ChrisRackauckas-Claude <accounts@chrisrackauckas.com>
Date: Wed, 9 Sep 2026 09:41:04 -0400
Subject: [PATCH] Prefer GITHUB_TOKEN for documentation deploy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Passing a stale org-level DOCUMENTER_KEY makes Documenter fetch
git@github.com over SSH and fail with "Could not read from remote
repository", even when GITHUB_TOKEN has contents:write. That is why
docs jobs that use the reusable workflow fail on deploy after the
build itself succeeds (SciMLWorkshop, MethodOfLines, MathML, …).

SSH deploy is now opt-in via use-documenter-key. Checkout no longer
persists credentials, and the job requests contents:write.
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Grok <noreply@x.ai>
Agent-Harness: Grok Build 1.0.24
Agent-Model: grok-4.6
Agent-Session: 01a08654-45f1-7a53-849c-56a7f1531d56 (local Grok Build session; no public conversation URL)
---
 .github/workflows/documentation.yml | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 08b3eb3..6520e3d 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -55,12 +55,22 @@ on:
         description: "Prevent the workflow run from failing if/when the job fails"
         required: false
         type: boolean
+      use-documenter-key:
+        description: "Deploy with DOCUMENTER_KEY over SSH instead of GITHUB_TOKEN. Default false: a stale org-level DOCUMENTER_KEY makes Documenter try `git@github.com` and fail even when GITHUB_TOKEN has contents:write."
+        default: false
+        required: false
+        type: boolean
 
 jobs:
   tests:
     name: "Build and Deploy Documentation"
     continue-on-error: ${{ inputs.continue-on-error || inputs.julia-version == 'nightly' }}
     runs-on: ${{ inputs.runner != '' && fromJson(inputs.runner) || (inputs.self-hosted && 'self-hosted' || inputs.os) }}
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: write
+      statuses: write
     env:
       # Whether this run has credentials that can actually push to gh-pages. GitHub issues a
       # read-only GITHUB_TOKEN, and withholds secrets such as DOCUMENTER_KEY, for pull
@@ -71,6 +81,8 @@ jobs:
                 && github.actor != 'dependabot[bot]') }}
     steps:
       - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: "Setup Julia ${{ inputs.julia-version }}"
         uses: julia-actions/setup-julia@v3
@@ -95,7 +107,7 @@ jobs:
           # Documenter report `Deploying: ✗` and exit 0, so a fork or Dependabot pull request
           # still reports whether the documentation *builds*, which is all it can verify.
           GITHUB_TOKEN: ${{ env.CAN_DEPLOY_DOCS == 'true' && (inputs.github-token || secrets.GITHUB_TOKEN) || '' }}
-          DOCUMENTER_KEY: ${{ env.CAN_DEPLOY_DOCS == 'true' && (inputs.documenter-key || secrets.DOCUMENTER_KEY) || '' }}
+          DOCUMENTER_KEY: ${{ env.CAN_DEPLOY_DOCS == 'true' && inputs.use-documenter-key && (inputs.documenter-key || secrets.DOCUMENTER_KEY) || '' }}
         run: ${{ inputs.debug-documenter && 'JULIA_DEBUG="Documenter"' || '' }} julia --color=yes --project=docs/ ${{ inputs.coverage && '--code-coverage=user' || '' }} docs/make.jl
 
       - name: "Filter coverage directories to those that exist"