Skip to content

fix: skip docs build/publish on pull_request, not just push - #222

Open
petercorke wants to merge 1 commit into
masterfrom
fix/skip-docs-publish-on-pr
Open

petercorke wants to merge 1 commit into
masterfrom
fix/skip-docs-publish-on-pr

Conversation

@petercorke

Copy link
Copy Markdown
Collaborator

Summary

The `sphinx` job in `master.yml` runs unconditionally on every trigger -- `push` (merge to master/future) and `pull_request`. On a PR whose branch lives in a fork -- including the author's own fork (this is what happened on #198) -- the job's final "push to gh-pages" step always fails:

```
remote: Permission to rai-opensource/spatialmath-python.git denied to github-actions[bot].
fatal: unable to access '...': The requested URL returned error: 403
```

This is GitHub Actions' own security policy: `GITHUB_TOKEN` is hardcoded read-only for `pull_request`-triggered runs whenever the head repo differs from the base repo, regardless of any repo/workflow permission settings. Not a bug in this repo, not fixable by changing settings -- the fix is to simply not attempt the gh-pages publish during PR runs at all, which is also the right behaviour independent of the permission issue (unreviewed PR content shouldn't land on the live public docs site).

What's changed

  • `master.yml`: added `if: ${{ github.event_name != 'pull_request' }}` to the `sphinx` job, so it (and the whole reusable `sphinx.yml` workflow it calls) is skipped entirely on PR runs, and only runs on `push`.
  • `sphinx.yml`: removed a dead, commented-out attempt at this exact guard (`# if: ${{ github.event_name != 'pull_request' }}`). 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. The condition has to live on the caller job (in `master.yml`), which does see the real event.

Side benefit

PR runs no longer spend ~10+ minutes building docs that were never going to be published anyway.

Test plan

  • Both edited YAML files parse as valid YAML
  • Traced the actual failure to this cause via perf: defer Matplotlib import until something actually plots #198's CI log and GitHub's documented `GITHUB_TOKEN` permissions for fork-originated `pull_request` events
  • Can't locally simulate GitHub's `workflow_call` event-name substitution, but the fix follows GitHub's own documented behaviour and this is a pure `if:`-condition change with no other logic touched

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.
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.

1 participant