MNT: Skip ReadTheDocs build on skip-ci commits#8636
Open
karlhillx wants to merge 3 commits into
Open
Conversation
Cadair
requested changes
May 16, 2026
Member
Cadair
left a comment
There was a problem hiding this comment.
Thanks for the PR, this is a neat solution.
| jobs: | ||
| post_checkout: | ||
| - git fetch --unshallow || true | ||
| - echo aWYgZ2l0IGxvZyAtMSAtLWZvcm1hdD0lQiB8IGdyZXAgLWlxRSAnXFsoY2kgc2tpcHxza2lwIGNpKVxdJzsgdGhlbiBleGl0IDE4MzsgZmkK | base64 -d > skip.sh |
Member
There was a problem hiding this comment.
I'm not a fan on having this base64 encoded. I'd much rather have the script inside the tools/ directory if it's not possible to have it inline.
Can you link the RTD bug?
Author
There was a problem hiding this comment.
Addressed — script is now at tools/skip-rtd.sh and referenced directly from .readthedocs.yaml. No more base64.
The encoding was a workaround for RTD's YAML processing edge cases; keeping the script in tools/ sidesteps that cleanly.
RTD issue tracking the broader [skip ci] commit support gap: readthedocs/readthedocs.org#871
Address review feedback: move the base64-encoded bash logic out of the RTD config and into tools/skip-rtd.sh. The script is now readable and maintainable, and referenced directly from .readthedocs.yaml. RTD handles exit 183 as a build-cancellation signal, but inline shell in YAML jobs can trigger RTD's YAML processing edge cases with certain characters; a separate script file avoids this.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
When a commit is pushed with
[skip ci]or[ci skip], GitHub Actions respects the marker and skips the relevant workflow runs, but Read the Docs currently ignores it and triggers a full documentation build anyway.This PR adds a
post_checkouthook to.readthedocs.yamlthat checks the latest commit message for those skip markers. If one is found, the hook exits with code183, which Read the Docs officially uses to cancel the build cleanly. (We bypass the RTD YAML quote-stripping bug by executing it via a base64 string).This brings RTD's behavior in line with GHA, avoiding unnecessary build minutes for commits that intentionally skip CI while keeping normal documentation builds completely unchanged. (This matches the infrastructure update recently requested by the Astropy team).