Skip to content
Ark

RFC 0002 — Docsite deploy + Access gate

  • Status: Accepted (2026-05-26)
  • Date: 2026-05-26
  • Author: j + Claude
  • Tracking: RFC 0001 (Cut 1), PLAN.md §10 (docsite + gate), §14 Phase 4

Decisions confirmed (2026-05-26): deploy via GitHub Actions + wrangler (mirrors worker-deploy.yml); domain ark-docs.pages.dev (Cloudflare Pages default); auto-publish on merge to main (paths-filtered) + manual dispatch.

Summary

Section titled “Summary”

Cut 2 of the docsite: publish the Starlight site (apps/docs, built in Cut 1) to Cloudflare Pages on every merge to main, and gate it with Cloudflare Zero-Trust Access so only @7hoenix.com identities can reach it. No application auth code — the gate is infrastructure.

What ships in this RFC (in-repo)

Section titled “What ships in this RFC (in-repo)”
  • .github/workflows/docs-deploy.yml — on push to main touching docs sources (or manual dispatch): mise toolchain → bun install → moon run docs:build → wrangler pages deploy apps/docs/dist --project-name ark-docs --branch main. Concurrency-guarded.
  • site: 'https://ark-docs.pages.dev' in astro.config.mjs — correct canonical URLs + sitemap (clears Cut 1’s lone build warning).
  • wrangler as a dev dependency of apps/docs (+ a deploy script) so the deploy is self-contained and version-pinned.
  • docs/reference/docsite-deploy.md — the runbook for the manual Cloudflare steps below.

What is NOT code (manual, one-time — see the runbook)

Section titled “What is NOT code (manual, one-time — see the runbook)”

These are account/dashboard actions that can’t live in the repo:

  1. CLOUDFLARE_API_TOKEN repo secret — custom token with Account → Cloudflare Pages → Edit (add Workers Scripts → Edit too so the same token also unblocks worker-deploy.yml). Optional CLOUDFLARE_ACCOUNT_ID if the token spans multiple accounts.
  2. Create the Pages project ark-docs with production branch main (wrangler pages project create ark-docs --production-branch=main, or via dashboard).
  3. Zero-Trust Access application over ark-docs.pages.dev with one policy: Allow when email ends with @7hoenix.com, plus a login method (One-time PIN works with no IdP).

Decisions on record

Section titled “Decisions on record”

D1 — Deploy mechanism → GitHub Actions + wrangler

Section titled “D1 — Deploy mechanism → GitHub Actions + wrangler”

Consistent with the existing worker-deploy.yml (same secret, same bun x wrangler shape); build config stays in-repo and reviewable. Rejected: Cloudflare Pages’ Git integration — dashboard-managed build settings and CF’s GitHub app needs access to this private repo.

D2 — Trigger → push to main (paths-filtered) + workflow_dispatch

Section titled “D2 — Trigger → push to main (paths-filtered) + workflow_dispatch”

Docs aren’t versioned releases like jg-ios/jg-api (no tag scheme); they should always reflect main. Paths filter (docs/**, apps/docs/**, PLAN.md, **/CHANGELOG.md, the workflow itself) avoids deploying on unrelated pushes. Manual dispatch re-deploys main on demand.

D3 — Domain → ark-docs.pages.dev

Section titled “D3 — Domain → ark-docs.pages.dev”

Zero DNS setup; a custom domain (e.g. docs.7hoenix.com) can be added later in the dashboard + a one-line site change. The Access gate applies regardless of domain.

Verification & limits

Section titled “Verification & limits”
  • The workflow + site build are verifiable in CI (the build runs; site clears the warning).
  • End-to-end deploy + gate cannot be tested from the repo — they depend on the secret and the Zero-Trust config. First real publish happens after the manual steps; the runbook is the contract.

Out of scope

Section titled “Out of scope”
  • Custom domain / DNS (later).
  • Gating Pages preview deployments (only the production domain is gated here).
  • Pulling app elm-books into the site (still deferred from RFC 0001).