Skip to main content

ADR 0061: Publish Derived Human Documentation After Quality

Status: Superseded by ADR 0062

Date: 2026-07-30

Context​

The Docusaurus interface makes STAGE easier to read than the repository tree, especially away from the development machine. A manual upload would make the public site drift from canonical source and turn routine documentation fixes into an avoidable release chore.

The source repository may remain private while the derived reading interface is public. Public output therefore needs a deliberate content boundary and must never be treated as proof that the underlying private repository is safe to disclose.

Decision​

Publish the generated static site at https://stage.zoshachi.com through GitHub Pages backed by the dedicated public chifunt/stage-game-engineering-docs repository. Keep this canonical source repository private.

The publication workflow:

  • runs automatically only after STAGE quality gate succeeds for main;
  • checks out the exact revision reported by that completed workflow;
  • may also be invoked manually by the repository owner;
  • installs the pinned documentation lockfile and builds Docusaurus;
  • screens the generated artifact for local machine paths and high-confidence credential shapes;
  • checks out the public documentation repository through a dedicated write-enabled deploy key;
  • replaces only that repository's gh-pages branch with website/build/; and
  • leaves GitHub Pages in the public repository responsible only for serving that already-screened branch.

The source repository remains canonical and may remain private. The public site contains selected generated documentation output, not Git history, source control credentials, local files, or an editing interface.

The deploy key is scoped to the public documentation repository. Its private half is stored only as the STAGE_DOCS_DEPLOY_KEY Actions secret in this canonical repository. It grants no write access back to canonical STAGE source.

The custom domain uses a one-time DNS CNAME from stage.zoshachi.com to chifunt.github.io. DNS and the public repository's Pages custom-domain setting remain account-level owner operations.

Alternatives Considered​

  • Manual uploads are simple once but create recurring drift and forgotten publication steps.
  • Cloudflare Pages direct upload supports private repositories and custom domains, but requires a Cloudflare API token and account/project secret configuration for CI.
  • Making the canonical repository public would avoid the publication mirror, but would unnecessarily disclose trials, local path evidence, and method implementation when readers need only the generated guide.
  • Cloudflare's Git integration would add another repository installation and deployment owner when GitHub Actions already runs the prerequisite quality gate.
  • Publishing the source repository would simplify source links but is a separate disclosure decision and is not required to make the human guide public.

Consequences​

  • Canonical documentation changes on main become visible after the quality workflow and Pages deployment finish.
  • A quality failure blocks publication instead of publishing a known-broken reading surface.
  • The generated site is publicly reachable and must be written accordingly.
  • The safety screen catches a bounded set of high-confidence leaks; it is not a general secret-management guarantee or substitute for reviewing public content.
  • Initial setup still requires enabling GitHub Pages on the public publishing repository and configuring the DNS record and custom domain once.
Last updated on