Axis / Documentation publication

Documentation publication

The publication workflow builds the repository Markdown with Jekyll and uploads _site to the Cloudflare Pages project axis. It runs on pushes to the default branch and manual runs on that branch. Source links still point to the corresponding GitHub commit. The publishing dependencies and layout remain under .github/pages/.

Deployment is disabled unless the repository Actions variable CLOUDFLARE_PAGES_ENABLED is exactly true. This is a setup gate, not authentication: Cloudflare Access must protect the site before enabling uploads. The workflow does not create or verify Access policies.

Cloudflare setup

1. Create a Direct Upload Pages project with Wrangler: run npx wrangler login, then npx wrangler pages project create axis --production-branch=trunk. This explicitly sets the repository’s current default branch as production. Do not enable a separate Git integration; GitHub Actions supplies the built files. If you choose another project name, update --project-name in the workflow. Use the actual pages.dev hostname shown by Cloudflare below; it may have a suffix if the desired hostname is already taken.
2. Make the initial deployment contain only a harmless placeholder index.html, using drag and drop or Wrangler. This establishes the project’s URLs without uploading the documentation before access control exists.
3. Add axis.pub under the project’s Custom domains and follow the DNS instructions. Associate the domain before enabling Access on it; Pages cannot add a custom domain that already has an Access policy. The initial site should still contain only the placeholder.
4. In the Pages project settings, enable the Access policy for previews. In Zero Trust, edit that generated application’s public hostname to remove the wildcard, protecting <project>.pages.dev. Return to the Pages settings and enable the preview policy again. Verify that both <project>.pages.dev and *.<project>.pages.dev have Access applications.
5. Create another Access application for the entire axis.pub hostname, without a path restriction. Cover any additional custom hostname, such as www.axis.pub, if configured.
6. In every application, replace the generated allow rules with an Allow policy for the exact email addresses that may view the documentation. Configure an identity provider or email one-time PIN. Do not leave an Everyone allow rule or a general bypass rule. Apply the same audience to production, previews and the custom domain.
7. Test the placeholder in a signed-out browser on the custom domain, production hostname and deployment hostname. Each must require login; an authorized login must reach the placeholder. Follow Cloudflare’s certificate-validation guidance if Access affects domain validation or renewal.

Cloudflare documents the production, preview and custom-domain policy setup in Pages known issues. The preview protection switch alone does not protect production or the custom domain.

GitHub setup

In repository Settings, create the Actions environment cloudflare-pages. Restrict its deployment branches to trunk, updating that restriction if the default branch changes. Add these environment secrets:

Use an API token rather than the global API key. The workflow requires only GitHub contents: read; it does not need GitHub Pages or OIDC permissions. Cloudflare describes token creation and CI uploads in Direct Upload with continuous integration.

Once all Access policies have been verified, create the repository-level Actions variable CLOUDFLARE_PAGES_ENABLED=true. It must be a repository variable because the job condition is evaluated before environment variables become available. Run Publish documentation manually on trunk, or push to that branch.

Retire GitHub Pages and verify

Replacing the workflow does not remove the previously published GitHub Pages deployment. In repository Settings > Pages, unpublish the old site and disable its publishing source. Keep ownership verification for the domain; if removing the GitHub Pages configuration, ensure the DNS records now target Cloudflare Pages rather than GitHub. GitHub describes unpublishing and disabling a Pages site.

After deployment, verify that signed-out requests to axis.pub, <project>.pages.dev and a deployment URL receive Access authentication instead of documentation. Check both a document and /assets/style.css. Verify that an unauthorized identity is denied, an authorized identity can navigate the documentation, and the old GitHub Pages origin no longer serves it.

Setting CLOUDFLARE_PAGES_ENABLED=false stops future workflow uploads; it does not close or remove an existing site. To make the documentation public later, change the Cloudflare Access policies deliberately.