Deploy docs via Pages artifact instead of gh-pages branch#832
Merged
mike-thompson-day8 merged 1 commit intomasterfrom Apr 10, 2026
Merged
Deploy docs via Pages artifact instead of gh-pages branch#832mike-thompson-day8 merged 1 commit intomasterfrom
mike-thompson-day8 merged 1 commit intomasterfrom
Conversation
The current docs workflow commits the entire built MkDocs site to the gh-pages branch on every push to master. Over time this has accumulated ~100 MB of generated artifacts (js/docs.js, klipse_plugin.js, etc.) in the gh-pages branch, which every git clone has to download. Switch to the artifact-based actions/deploy-pages flow so the site is served from an ephemeral workflow artifact and nothing is committed to git. Once the new deployment is verified the gh-pages branch can be deleted, reducing clone size from ~100 MB to ~5 MB. Refs #831
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
1 participant
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
Closes #831.
The current docs workflow commits the entire built MkDocs site to the
gh-pagesbranch on every push to master. Over time this has accumulated~100 MB of generated artifacts in
gh-pages(js/docs.jsat 1.8 MB ×626 versions,
klipse_plugin.jsat 7.6 MB,re-frame-docs-app.tar.xz,etc.) — and every
git clonehas to download all of it.This PR switches the third job of
docs-workflow.ymlfrom "commit thebuilt site to
gh-pages" to the modern artifact-basedactions/deploy-pagesflow. The site is served directly from anephemeral workflow artifact, nothing is committed to git, and the
gh-pagesbranch is no longer needed.The first two jobs (
re-frame-docs-app,mkdocs) are unchanged.Required follow-up steps (after this merges)
(
gh-pages) to "GitHub Actions". This must happen before the newworkflow runs successfully — otherwise the
deploy-pagesstep willfail and the site will keep serving stale content from
gh-pages.https://day8.github.io/re-frame/, delete the
gh-pagesbranch:git push origin --delete gh-pagesclone should drop from ~100 MB to ~5 MB.
Notes
introduced in Pin GitHub Actions to commit SHAs #830.
permissionsare scoped only to the newgithub-pagesjob(
pages: write,id-token: write) so the existingre-frame-docs-appandmkdocsjobs are not affected.concurrency: pagesblock is added to preventoverlapping Pages deployments without cancelling in-flight runs.
PREREQUISITEheader comment sofuture maintainers reading the diff understand the Pages source must
be set to "GitHub Actions".
Test plan
gh-pagesbranch deleted; clone size verified to drop after GC