Repository navigation
ci: deploy the documentation to a Cloudflare R2 bucket - #4355
Conversation
The site moves off GitHub Pages to an R2 bucket served through Cloudflare, reached over the S3 interface, so revert the `gh-pages` deployment added in scikit-hep#4323. Add a `purge-cloudflare-cache` composite action in place of the CloudFront invalidation, and drop the `deploy-to-gh-pages` action along with the workflow that squashed the branch history, which only existed because every deployment committed a full copy of the rendered site. Pull request previews return to their own bucket at `/PR<number>`. They are replaced in place on every push, so upload them with a `Cache-Control` that makes the edge revalidate rather than purging the whole zone for each one; Cloudflare only offers purge-by-prefix on Enterprise plans. Previews are still removed once their pull request closes, since nothing else would ever overwrite them. R2 needs an access key rather than OIDC, so the deployment jobs take `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`, and the purge takes `CLOUDFLARE_ZONE_ID` and `CLOUDFLARE_API_TOKEN`. Assisted-by: claude-code:claude-opus-5
An R2 custom domain serves objects by exact key and has no index document, unlike the S3 website endpoint it replaces, so `/doc/main` and `/PR<number>` are both a 404. Only the directory itself can be rewritten to the `index.html` it holds, and that rewrite keys off the trailing slash. Assisted-by: claude-code:claude-opus-5
A bucket name is no longer the domain it is served on, since R2 bucket names cannot contain a dot. Assisted-by: claude-code:claude-opus-5
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Pull request overview
Moves docs hosting/deployment from GitHub Pages (gh-pages) to a Cloudflare R2 bucket via the S3 API, including cache purging and updated preview URLs.
Changes:
- Replace
gh-pagespublishing withaws s3 sync/cpuploads to R2 formain,stable, and versioned docs. - Add a composite action to purge the Cloudflare zone cache after deploys.
- Update PR preview deployment/cleanup to write/remove
/PR<number>/keys in a dedicated preview bucket.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| .github/workflows/reusable-docs.yml | Switch deploy from gh-pages commits to R2 uploads + Cloudflare purge |
| .github/workflows/docs-version.yml | Publish version switcher to R2 + purge cache |
| .github/workflows/docs-squash.yml | Remove no-longer-needed gh-pages history squash workflow |
| .github/workflows/docs-preview.yml | Upload PR preview artifacts to R2 under /PR<number>/ |
| .github/workflows/docs-preview-cleanup.yml | Remove PR preview prefix from the preview bucket on PR close |
| .github/workflows/ci.yml | Forward R2/Cloudflare secrets into the reusable docs workflow |
| .github/actions/purge-cloudflare-cache/action.yml | Add composite action to purge Cloudflare zone cache |
| .github/actions/deploy-to-gh-pages/action.yml | Remove the gh-pages deployment composite action |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The documentation is generated with one page per callable, so a renamed or deleted function used to leave an orphan behind that the site kept serving and that counted against the storage of the bucket. Sync with `--delete`, which also restores what the `gh-pages` deployment did by rewriting its target. A preview now ends in a slash as well, so that the prefix it deletes under cannot reach the previews of other pull requests. Retry the cache purge, since it is idempotent and a transient failure would otherwise fail a deployment whose upload had already succeeded, and report the reason the API gives for a refused purge. Assisted-by: claude-code:claude-opus-5
|
The documentation preview is ready to be viewed at https://awkward-array.org/doc/pr/4355/ |
|
@ianna and @TaiSakuma I tested this in a fork and it works well, so it should be ready to go |
🤖 AI text below 🤖
The documentation site is moving off GitHub Pages to a Cloudflare R2 bucket, reached over the S3 interface, so this reverts the
gh-pagesdeployment added in #4323.What changed
deploy-to-gh-pagesand the workflow that squashed the branch history are gone. The latter only existed because every deployment committed a full copy of the rendered site to a git branch.purge-cloudflare-cachecomposite action replaces the CloudFront invalidation. It purges the whole zone, since Cloudflare only offers purge-by-prefix on Enterprise plans, and the zone serves nothing but the documentation. A refused purge is reported in the body of a200, so the action checks.successrather than the status code./PR<number>. They are replaced in place on every push, so they are uploaded with aCache-Controlthat makes the edge revalidate, rather than purging the zone for every push./doc/mainand/PR<number>are both a 404.The layout of the site is unchanged from before #4323.
Before this can be merged
Five repository secrets are needed:
R2_ACCOUNT_ID,R2_ACCESS_KEY_ID,R2_SECRET_ACCESS_KEY,CLOUDFLARE_ZONE_IDandCLOUDFLARE_API_TOKEN, the last with theCache Purgepermission. They have to be repository secrets rather thandocsenvironment secrets, becauseci.ymlforwards them into the reusable workflow from a job that does not itself declare the environment.On the Cloudflare side, both
awkward-array.organdpreview.awkward-array.orgneed a Transform Rule that rewrites a directory to theindex.htmlit holds:ends_with(http.request.uri.path, "/")concat(http.request.uri.path, "index.html")Enabling Smart Tiered Cache on the zone is also worth doing: it keeps a purge from multiplying origin fetches across data centres.