Skip to main content

ADR 0062: Serve The Public Documentation Mirror Through Cloudflare Pages

Status: Accepted

Date: 2026-08-01

Context​

ADR 0061 established the important publication boundary: a successful main quality run builds and screens the exact canonical revision, then writes only generated output to a dedicated public repository. GitHub Pages was initially selected to serve that mirror at stage.zoshachi.com.

During the custom-domain cutover, the generated artifact and DNS path were sound but GitHub Pages did not provision a usable certificate. Cloudflare already owns the domain's authoritative DNS and can serve the public mirror without receiving access to the private canonical repository or a deployment credential from its CI.

The public mirror changes the Git-integration tradeoff considered in ADR 0061. Connecting a host to that deliberately public generated-output repository does not expose the private source or let the host bypass the source repository's quality and screening workflow.

Decision​

Serve https://stage.zoshachi.com through the Cloudflare Pages project stage-game-engineering-docs, connected only to the public chifunt/stage-game-engineering-docs repository.

Keep the publication boundary from ADR 0061:

  • STAGE quality gate must succeed for main before automatic publication;
  • the publication workflow checks out that exact verified revision;
  • Docusaurus builds from canonical source and the generated artifact passes scripts/check_public_site.py;
  • the workflow replaces only the public mirror's gh-pages branch through the repository-scoped STAGE_DOCS_DEPLOY_KEY; and
  • the private source repository remains canonical and is not connected to Cloudflare.

Configure Cloudflare Pages as a static mirror consumer:

  • production branch: gh-pages;
  • framework preset: none;
  • build command: exit 0;
  • build output directory: .;
  • automatic production deployments: enabled; and
  • preview branch deployments: disabled.

Cloudflare owns the custom-domain and TLS configuration. The generated bundle does not carry GitHub Pages provider files such as CNAME or .nojekyll. Cloudflare does not require an API token in the canonical repository because its Git integration observes the already-public mirror.

GitHub Pages is no longer part of the intended serving path. Its existing configuration may remain temporarily as a rollback aid during cutover, then be disabled through the public repository's account settings without changing the canonical publication workflow.

Alternatives Considered​

  • Continue waiting for GitHub Pages certificate provisioning. This preserves fewer services but leaves the public custom domain without dependable HTTPS.
  • Upload directly to Cloudflare Pages from the canonical workflow. This would require a Cloudflare API token and duplicate the public mirror's role as the screened publication boundary.
  • Connect Cloudflare to the private canonical repository. This would broaden repository access and let Cloudflare build before the explicit quality and public-artifact screening boundary.
  • Make the canonical repository public. Public source disclosure remains a separate owner decision and is unnecessary for serving the generated guide.

Consequences​

  • The public path is now canonical source -> successful quality run -> screened public mirror commit -> Cloudflare Pages deployment.
  • Cloudflare sees only deliberately public generated files and public mirror history; it receives neither private source access nor a canonical-repository deployment secret.
  • A direct write to the mirror's gh-pages branch could still bypass the canonical quality gate. Treat that branch as generated output and use the canonical publication workflow for normal changes.
  • Publication health has two observable boundaries: the mirror commit and the Cloudflare deployment. Neither proves method correctness or human acceptance.
  • Cutover verification on 2026-08-01 confirmed valid HTTPS, successful handbook routes, and identical home-page content from the Pages project domain and stage.zoshachi.com.
Last updated on