Docs Publishing¶

All documentation deploys from a single hub workflow in this repository. Source repositories no longer carry GitHub Actions workflows.

Hub Workflow¶

The .github/workflows/deploy-hub.yml workflow:

1. Triggers on push to hub content or manual dispatch
2. Installs Nix and enters the dev shell with direnv
3. Runs scripts/build-all-docs.sh to build the hub landing page and all repo docs
4. Deploys the consolidated hub/site/ directory to Cloudflare Pages

The sites variable in variables.tf is the authoritative list of published repositories. The build script reads that definition directly.

Operational Model¶

1. Push documentation changes in the source repository.
2. Run the hub workflow manually, or deploy locally from this repository.
3. The hub workflow clones the latest default branch for external repos and uses the current checkout for this repository.

Only this repository needs Cloudflare deployment secrets.

Source repositories only need DOCS_DISPATCH_TOKEN. They do not need direct Cloudflare deployment secrets when using the centralized docs hub flow.

Hetzner Runner Canary¶

The hub deploy workflow can run on the Hetzner ARM canary runner when the repository variable CI_CANARY_HETZNER=1 is enabled in this repository.

Recommended usage:

1. Keep source-repo docs workflows lightweight and dispatch-only.
2. Use Hetzner in source repos for smoke/static checks where ARM coverage is useful.
3. Keep heavyweight or architecture-sensitive builds on GitHub-hosted runners until they are proven stable on the self-hosted fleet.

Manual Deploy¶

# Deploy all docs locally (uses workspace repos)
just deploy-all

# Deploy hub landing page only
just deploy-hub