github/workflows: Deploy docs previews for pull requests.#19389
Open
mattytrentini wants to merge 1 commit into
Open
github/workflows: Deploy docs previews for pull requests.#19389mattytrentini wants to merge 1 commit into
mattytrentini wants to merge 1 commit into
Conversation
Build the documentation for pull requests that touch docs/ or tests/cpydiff/ and publish it to a separate repository (<owner>/micropython-docs-previews) served via GitHub Pages, under a per-PR directory (pr-<N>/). The preview link is posted as a comment on the PR, and the directory is removed when the PR is closed. Previews live in a separate repository so this repository's history and clone size are never affected. The build runs under pull_request with a read-only token so untrusted fork code never gains write access; a separate workflow_run job performs the privileged publish using a repo-scoped SSH deploy key held in the PREVIEW_DEPLOY_KEY secret. The PR number passed from the build is validated before use, and the deploy and cleanup jobs skip cleanly when PREVIEW_DEPLOY_KEY is not set, so the workflows are inert on forks and until a maintainer configures the previews repository. Signed-off-by: Matt Trentini <matt.trentini@gmail.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #19389 +/- ##
=======================================
Coverage 98.51% 98.51%
=======================================
Files 176 177 +1
Lines 22904 22927 +23
=======================================
+ Hits 22563 22586 +23
Misses 341 341 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
Code size report: |
Contributor
|
I like the ability to quickly indpect the changes. With the exclusion of th |
Josverl
suggested changes
Jun 28, 2026
| fi | ||
| - name: Download docs artifact | ||
| if: steps.config.outputs.enabled == 'true' | ||
| uses: actions/download-artifact@v4 |
Contributor
There was a problem hiding this comment.
Current version is download-artifact@v8.0.1 and uses the current supported nodejs
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.
Summary
Build the documentation for pull requests that touch
docs/ortests/cpydiff/(notpy/) and publish it to a separate repository (/micropython-docs-previews) served via GitHub Pages, under a per-PR directory (pr-<N>/). The preview link is posted as a comment on the PR, and the directory is removed when the PR is closed.Previews live in a separate repository so this repository's history and clone size are never affected. The build runs under pull_request with a read-only token so untrusted fork code never gains write access; a separate workflow_run job performs the privileged publish using a repo-scoped SSH deploy key held in the PREVIEW_DEPLOY_KEY secret. If this is merged, I'll need some help setting this up in the micropython organization.
The PR number passed from the build is validated before use, and the deploy and cleanup jobs skip cleanly when PREVIEW_DEPLOY_KEY is not set, so the workflows are inert on forks and until a maintainer configures the previews repository.
Testing
I tested by merging this in my fork and then configuring a repo/token. Raising a dummy PR that modified docs published the docs to the repo. Removing the PR removed the published docs.
Trade-offs and Alternatives
I initially started by publishing to the micropython repository but this cost commits for each PR as it requires modifications to the
gh_pagesfolder. Not ideal.I also investigated using external services including Read the Docs and Cloudflare Pages. Both were possible but had tradeoffs; RtD had limits on the number of active branches supported and both meant using an external service with an account to manage.
We'll need to keep an eye on the size of the pages deployed, GitHub has a limit of ~1GB of gh_pages content. Each deployment of the docs consumes ~20MB so we'd need ~50 active PRs that modify docs to exceed the limit. Very unlikely. But worth keeping in mind if GitHub reduce the limit or if we have a spate of PRs.
Generative AI
I used generative AI tools when creating this PR, but a human has checked the
code and is responsible for the code and the description above.