Skip to content

ci: deploy the documentation to a Cloudflare R2 bucket - #4355

Merged
ianna merged 6 commits into
scikit-hep:mainfrom
ariostas:ariostas/deploy-docs-to-r2
Sep 18, 2026
Merged

ianna merged 6 commits into
scikit-hep:mainfrom
ariostas:ariostas/deploy-docs-to-r2

Conversation

@ariostas

Copy link
Copy Markdown
Member

🤖 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-pages deployment added in #4323.

What changed

  • deploy-to-gh-pages and 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.
  • A purge-cloudflare-cache composite 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 a 200, so the action checks .success rather than the status code.
  • Pull request previews return to their own bucket at /PR<number>. They are replaced in place on every push, so they are uploaded with a Cache-Control that makes the edge revalidate, rather than purging the zone for every push.
  • Previews are still removed once their pull request closes. Nothing else would ever overwrite them, so they would otherwise accumulate for as long as the project lives.
  • URLs pointing at a directory now end in a slash. 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.

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_ID and CLOUDFLARE_API_TOKEN, the last with the Cache Purge permission. They have to be repository secrets rather than docs environment secrets, because ci.yml forwards them into the reusable workflow from a job that does not itself declare the environment.

On the Cloudflare side, both awkward-array.org and preview.awkward-array.org need a Transform Rule that rewrites a directory to the index.html it holds:

  • If ends_with(http.request.uri.path, "/")
  • Rewrite the path to 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.

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
@github-actions github-actions Bot added the type/ci PR title type: ci (set automatically) label Sep 15, 2026
@codecov

codecov Bot commented Sep 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.10%. Comparing base (c762767) to head (308a6ed).
✅ All tests successful. No failed tests found.

Additional details and impacted files

see 1 file with indirect coverage changes

@ariostas
ariostas requested a lite review from Copilot September 15, 2026 19:30

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-pages publishing with aws s3 sync/cp uploads to R2 for main, 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.

Comment thread .github/workflows/docs-preview.yml Resolved
Comment thread .github/workflows/reusable-docs.yml Resolved
Comment thread .github/workflows/reusable-docs.yml Resolved
Comment thread .github/workflows/reusable-docs.yml Resolved
Comment thread .github/workflows/docs-version.yml Resolved
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
@github-actions

Copy link
Copy Markdown
Contributor

The documentation preview is ready to be viewed at https://awkward-array.org/doc/pr/4355/

@ariostas
ariostas marked this pull request as ready for review September 17, 2026 15:35
@ariostas

Copy link
Copy Markdown
Member Author

@ianna and @TaiSakuma I tested this in a fork and it works well, so it should be ready to go

@ianna ianna left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ariostas — fantastic! Let’s merge it. Thank you.

@ianna
ianna enabled auto-merge (squash) September 18, 2026 06:00
@ianna
ianna merged commit abd252d into scikit-hep:main Sep 18, 2026
45 checks passed

This branch was previously deployed

1 inactive deployment
docs — 308a6edc Deployed Sep 18, 2026 by ianna via Remove Branch Preview #25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type/ci PR title type: ci (set automatically)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants