ci: publish the documentation site to the Cloudflare project that owns it - #82
Merged
Conversation
The site had no publication in this repository. Its pages are generated from the binary, committed, and gate-checked on every pull request — and then never left git. Measured against the live site today: the reference still describes `protection`, `minimum_generations` and `recovery_window`, keys that no longer exist; it lists seventeen error codes deleted this week; the capability page still says "no drill is run, and no service can currently prove a backup would restore"; and /guides/back-up-a-database is a 404. Documentation that is verified and unpublished is documentation nobody reads, and a published page describing a schema the binary rejects is worse than no page. Deploys to GitHub Pages from main on any change to the site or the generated reference, and on demand. main rather than a release tag: the reference is regenerated from the binary at HEAD and committed beside it, so main is where the documentation and the code it describes agree. The job runs the same build the gate runs — `astro check`, the build, and check-tables.mjs — and then refuses to publish if that build modified any committed page, because a site whose reference does not match the committed one is a repository state that should not reach main, let alone onebox.run. site/public/CNAME carries the custom domain into the artifact. Pointing the domain at Pages is a DNS change nobody can make from a workflow; until that happens this publishes to the github.io address and changes nothing for visitors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…s it onebox.run is a Cloudflare Pages project — `onebox`, with the custom domain already attached — published by hand: it lists no git provider, and the pages had drifted a long way behind the binary. The live reference named `protection`, `minimum_generations` and `recovery_window`, keys the binary now rejects. It listed seventeen error codes deleted this week. The capability page said no service could prove a backup would restore, after drills became executable. The backup guide was a 404. Publication is now something the repository does. On any change to the site or the generated reference, and on demand, the same build the gate runs — `astro check`, the build, and check-tables.mjs — is published to that project with `wrangler pages deploy`. Cloudflare rather than GitHub Pages because the domain, its certificate and its CDN are already there. Publishing into the path already in use needs one API token; moving to Pages would need a live DNS cutover and buy nothing. Before publishing it refuses a build that modified any committed page: a site whose reference does not match the committed one is a repository state that should not reach main, let alone onebox.run. That guard is what would have caught this drift. Needs CLOUDFLARE_API_TOKEN (Pages:Edit) and CLOUDFLARE_ACCOUNT_ID as repository secrets. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The page summary still told readers that "a row marked reserved is one no path raises yet", describing a column that went with the nineteen unreachable codes. It now says what the table means: every code in it is raised by a path in the shipped binary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
vishr
changed the title
An account id is an identifier, not a credential — it is what sits in a committed wrangler.toml on every project that has one. Carrying it as a repository secret bought no secrecy and doubled what somebody has to set up before the site can publish itself. CLOUDFLARE_API_TOKEN, scoped to Pages:Edit, is now the only thing this workflow needs that is not in the repository. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
onebox.runis a Cloudflare Pages project —onebox, custom domain already attached — published by hand:wrangler pages project listreportsGit Provider: No. That is why it had drifted.What the live site was serving
/reference/fields/servicesprotection,minimum_generations,recovery_window— keys the binary now rejects/reference/errors/status/capabilities/guides/back-up-a-databaseA published page describing a schema the binary refuses is worse than no page.
This PR
Publication becomes something the repository does. On any change to
site/**ordocs/**, and on demand, the same build the gate runs —astro check, the build,check-tables.mjs— is deployed to theoneboxproject withwrangler pages deploy.Cloudflare, not GitHub Pages: the domain, its certificate and its CDN are already there. Publishing into the path already in use needs one API token; moving to Pages would need a live DNS cutover and buy nothing.
Refuses to publish a build that modified any committed page — the guard that would have caught this drift.
Also corrects the errors-page summary, which still explained a "reserved" column that no longer exists.
Needs two repository secrets
CLOUDFLARE_API_TOKEN— Pages:EditCLOUDFLARE_ACCOUNT_IDAlready published
I deployed the current
mainbuild by hand from an authenticated session, so onebox.run is correct now rather than after this merges. This PR is what stops it drifting again.🤖 Generated with Claude Code