From 8c04681d4bfd817be5b02eca0a1d3589e4f00071 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Tue, 15 Sep 2026 22:20:36 +0200 Subject: [PATCH] fix: skip docs build/publish on pull_request, not just push The sphinx job unconditionally ran (and tried to publish to gh-pages) on every PR, including ones whose branch lives in a fork -- even the author's own fork (e.g. #198). GitHub Actions always issues a read-only GITHUB_TOKEN for pull_request-triggered runs when the head repo differs from the base repo, so the gh-pages push step there fails by design, regardless of repo/workflow permission settings. There was already a commented-out attempt at this exact guard inside sphinx.yml itself (`if: github.event_name != 'pull_request'`), but it could never have worked there: sphinx.yml is invoked via `workflow_call`, and github.event_name inside a called workflow is always "workflow_call", never the original triggering event. Moving the condition to the caller job in master.yml (which does see the real triggering event) is what actually works -- removed the dead comment from sphinx.yml accordingly. This also means PR runs no longer spend ~10+ minutes building docs that were never going anywhere, and unreviewed PR content never reaches the live public docs site. --- .github/workflows/master.yml | 8 +++++++- .github/workflows/sphinx.yml | 1 - 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/master.yml b/.github/workflows/master.yml index 9e8a7fa7..210d1237 100644 --- a/.github/workflows/master.yml +++ b/.github/workflows/master.yml @@ -77,6 +77,12 @@ jobs: file: ./coverage.xml sphinx: # If the above worked: - # Build docs and upload to GH Pages + # Build docs and upload to GH Pages -- only on push (merge to master/future), + # never on pull_request: a PR whose branch lives in a fork (including the + # author's own fork) gets a read-only GITHUB_TOKEN by GitHub's own design, + # so the gh-pages push step always fails there regardless of repo settings. + # Publishing unreviewed PR content to the live docs site isn't desired + # either way. needs: unittest + if: ${{ github.event_name != 'pull_request' }} uses: ./.github/workflows/sphinx.yml diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index c0beb95a..445d7181 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -6,7 +6,6 @@ on: jobs: sphinx: runs-on: ubuntu-22.04 - # if: ${{ github.event_name != 'pull_request' }} steps: - uses: actions/checkout@v4 - name: Set up Python 3.12