Cloudflare Pages with Git integration

Decision date: 2026-10-05. Status: accepted configuration. Actual publication is recorded independently in this site’s deployment and hosted-check receipts, with the deployed Git identity.

Context

The owner instructed this project to follow the GCP Security Handbook’s Cloudflare deployment procedure. The primary references are its root deployment guide and update guide, with supporting engineering design and runbook, pinned to ce2fcafbc8bd06adaafc47b6491f6e8771224679. Their measured publication outcomes belong to the handbook, not to this website.

The website already produces static Astro/Starlight HTML, local diagrams, reviewed evidence derivatives/originals, and Pagefind. The private authoring repository is devSatym/resilience-gate-docs; the public platform remains an independently pinned upstream input. The earlier Workers Static Assets selection in decision 006 is superseded. Its retained audit receipts remain historical.

Decision

Use a Git-integrated Cloudflare Pages Free project named resilience-gate-docs, connected only to that private documentation repository. Native builds use production branch main, root site, output dist, and Node 22.20.0. The native command explicitly supplies DOCS_SITE=<reviewed stable origin> npm run build:cloudflare. Keep the root base /, static rendering, Pagefind, all 34 reviewed originals, and the existing reader experience. No SSR, Pages Functions, Worker application, or storage service is added.

Create the project through the native Git-source Pages API after the owner grants the Cloudflare Workers and Pages GitHub App access. Initially pause production/preview deployment triggers and confirm the assigned Pages hostname. Separate configuration enables Git processing and all branch previews while automatic main production remains paused; then request an explicit first native Git build. A Direct Upload project is unsuitable for this editing workflow; it cannot later be converted to Git integration. After actual first-publication verification, enable automatic production pushes; the already configured branch previews remain enabled. Pages Git integration, Direct Upload

Use explicit stable DOCS_SITE for production, initially the confirmed https://resilience-gate-docs.pages.dev origin and then https://resilience-gate.devsatym.xyz for custom-origin promotion only after active Pages domain/certificate status and normal custom-host HTTPS success. The origin is supplied as a reviewed nonsecret shell prefix because pages_build_output_dir makes Wrangler configuration authoritative; dashboard vars alone were absent from the first native build. Keep Wrangler free of vars/bindings/runtime. Non-main previews still use validated CF_PAGES_URL and noindex/robots controls, with DOCS_SITE only as fallback. Wrangler source of truth Canonical, social, sitemap, and search output must be rebuilt together when the origin changes. Preview indexing controls do not make previews private.

Register the custom Pages subdomain before the owner adds CNAME resilience-gate → resilience-gate-docs.pages.dev at Spaceship. Pages supports this external-DNS subdomain without an active Cloudflare zone, apex transfer, or nameserver migration. An existing exact-host record or unrelated Pages association is a stop condition. The old Workers Billing Read and zone checks are not current Pages prerequisites. Pages custom domains

Keep GitHub Actions validation-only, independent from Pages’ native deployment triggers. Review preview and browser checks before production merges; Pages does not inherently wait for the GitHub workflow. Watch public build inputs, including curated engineering Markdown, while excluding private generated audits. No account visibility, unrelated DNS, nameserver, or paid-plan change is authorized by this decision.

Consequences and evidence

Continuous editing is available through native Git production/preview builds. Local saves do not publish. Pages Free currently permits 500 builds/month, one account-wide concurrent build, a 20-minute timeout, 20,000 static files, and 25 MiB per asset. Quotas and terms apply; no upgrade or unlimited-build commitment is made. Pages limits

A successful private repository push, native build, public DNS answer, certificate activation, and hosted article/search/original-image verification each have different evidence scopes. New results belong under docs/website/audit/cloudflare-pages/, with actual source/deployment/origin identity. Earlier monorepo, private-transfer, and Workers-campaign receipts remain unchanged. Private source does not make the published website private.

The publication runbook defines local validation, account/Git-source inspection, paused initialization, native builds, the owner CNAME handoff, custom-origin promotion, continuous deployment, and strict public verification. No live pass or new test count is asserted by this decision.