From 0787a4bbfea1b04e4da53d8e3af8dbdeed84c211 Mon Sep 17 00:00:00 2001 From: Christian Diddens Date: Fri, 7 Aug 2026 15:45:10 +0200 Subject: [PATCH] Do not run the deploy step on pull requests A PR from a fork only ever gets a read-only GITHUB_TOKEN, whatever the permissions: contents: write declaration says, so the push to gh-pages always failed with a 403 and marked the run red. Nothing was published by those runs, and nothing could have been - see the runs on PRs #19-#22. Gating the deploy step on the event turns the PR check into what is actually useful there: it verifies that gen_page.sh still builds, which would catch e.g. an upstream readthedocs layout change breaking gen_example_gallery.py. Publishing still happens on push to main. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Fmhceke9votYhvWyGSBKyG --- .github/workflows/deploy.yml | 5 +++++ CLAUDE.md | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 0c1dc18..71a461d 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -26,6 +26,11 @@ jobs: ls _generated/* - name: Deploy 🚀 + # On a pull request the build above is the useful part: a PR from a fork + # only ever gets a read-only GITHUB_TOKEN, so the push to gh-pages below + # would fail with a 403 and mark the whole run red without publishing + # anything. Deploy only on push to main (and on workflow_dispatch). + if: github.event_name != 'pull_request' uses: JamesIves/github-pages-deploy-action@v4 with: folder: _generated diff --git a/CLAUDE.md b/CLAUDE.md index fc218f3..9df0ce3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,9 @@ The established flow (how PRs #19–#21 landed): The merge pushes to `upstream/main`, which triggers `.github/workflows/deploy.yml`: it installs the dependencies, runs `gen_page.sh` and force-pushes `_generated/` to the `gh-pages` branch via `JamesIves/github-pages-deploy-action`. That run takes ~20 s and is followed by GitHub's own "pages build and deployment" run. Check both with `gh run list --repo pyoomph/pyoomph.github.io`. -**A PR from a fork always shows a failing check — this is expected and not a defect in the change.** `deploy.yml` triggers on `pull_request` to `main` as well as on push, but for fork PRs GitHub scopes `GITHUB_TOKEN` to read-only regardless of the `permissions: contents: write` declaration. The build succeeds and only the final push to `gh-pages` fails with a 403, so nothing is published. The check goes green on merge, because a push to `main` runs with a writable token. Gating the deploy step with `if: github.event_name != 'pull_request'` would suppress the red X. +**On a PR the workflow builds but does not deploy.** `deploy.yml` triggers on `pull_request` to `main` as well as on push, but the deploy step is gated with `if: github.event_name != 'pull_request'`. So the PR check verifies that `gen_page.sh` still succeeds — a red X there means the build is genuinely broken, e.g. an upstream docs layout change tripping `gen_example_gallery.py` — and publishing happens only on the push to `main` after the merge. + +That gate exists because a PR from a fork gets a read-only `GITHUB_TOKEN` regardless of the `permissions: contents: write` declaration; before it was added, every fork PR (#19–#22) ended with a 403 on the push to `gh-pages` and a red X that meant nothing. ## How pages are assembled