Skip to content

Cloudflare Pages deployment

The documentation book is built by the (RHIZA) BOOK GitHub Actions workflow and published from the repository default branch to Cloudflare Pages. The Cloudflare deployment uses the book artifact produced by Rhiza.

The deployment is for internal documentation. Before giving anyone the URL, protect the production hostname and preview hostnames with Cloudflare Access.

Private hosting

Cloudflare is the sole documentation host. The Pages production and preview hostnames must remain protected by Cloudflare Access, allowing only Mark, Will, and Reuben.

Repository configuration

The workflow is in .github/workflows/rhiza_book.yml. The local book job runs Rhiza's book task to build _book/, validates the navigation, and uploads a book artifact. The deploy-cloudflare job downloads that artifact and runs:

pages deploy _book --project-name=$CLOUDFLARE_PAGES_PROJECT

The Cloudflare job runs only when a push targets the repository default branch. It omits Wrangler's --branch option so the deployment updates the production hostname. Pushes to other branches still build and validate the book, but do not deploy to Cloudflare.

The following GitHub repository settings are required. Set them in Settings > Secrets and variables > Actions.

Setting Name Value
Variable CLOUDFLARE_PAGES_PROJECT The Cloudflare Pages project name, for example pyrf-book
Secret CLOUDFLARE_ACCOUNT_ID The Cloudflare account ID that owns the Pages project
Secret CLOUDFLARE_API_TOKEN A scoped API token permitted to deploy to that Pages project

CLOUDFLARE_PAGES_PROJECT is a non-secret variable so the workflow can print the deployment URL. Keep the account ID and API token as secrets.

GitHub configuration

  1. Create the Pages project in Cloudflare before merging the workflow. wrangler pages deploy deploys to an existing project.
  2. In the GitHub repository, add the variable and secrets above. Do not put tokens in the workflow file, .env, or repository variables.
  3. Create a Cloudflare API token using the account that owns the project. Give it the account-level Cloudflare Pages: Edit permission, scoped to the required account. Avoid using the Global API Key.
  4. Push or merge a change to the default branch. Open the (RHIZA) BOOK workflow run and check the Deploy book to Cloudflare Pages job. Its summary prints the production URL.

The default Pages URLs are:

https://<project>.pages.dev/

For pyrf, the production URL is https://pyrf.pages.dev/.

Cloudflare Pages configuration

  1. In the Cloudflare dashboard, select the Ringfinity account.
  2. Go to Workers & Pages, choose Create application, then create a Pages project using Direct Upload. GitHub Actions performs the deployments, so do not configure Cloudflare's Git integration for this project.
  3. Choose the exact project name entered in CLOUDFLARE_PAGES_PROJECT and finish creating the project.
  4. After the first successful workflow run, confirm that the deployment is listed under the project and that the generated Pages URL serves the documentation.
  5. Prefer attaching a custom documentation hostname in a Cloudflare-managed Ringfinity zone. This gives the deployment a stable internal URL and makes Access policy ownership clear.

Do not configure a Cloudflare build command or output directory: the workflow uploads the already-built _book artifact.

Get CLOUDFLARE_ACCOUNT_ID

  1. In the Cloudflare dashboard, select the Ringfinity account and open Workers & Pages.
  2. Find Account Details on the Workers & Pages overview.
  3. Select the copy control beside Account ID.
  4. In GitHub, open Settings > Secrets and variables > Actions > Secrets, select New repository secret, name it CLOUDFLARE_ACCOUNT_ID, and paste the copied value.

The account ID identifies the Cloudflare account that owns the Pages project. It is not a credential, but store it as a GitHub secret to keep the workflow configuration consistent with its deployment credentials.

Create CLOUDFLARE_API_TOKEN

  1. In the Cloudflare dashboard, open the profile menu, then go to My Profile > API Tokens. Create the token in the Ringfinity account that owns the Pages project. An account-owned token is preferable when available because it is not tied to an individual user.
  2. Select Create Token, choose Create Custom Token, and give it a purpose-specific name such as GitHub Actions - pyrf Pages deploy.
  3. Under Permissions, add the account permission Cloudflare Pages: Edit.
  4. Under Account Resources, select Include > Specific account > Ringfinity. Do not authorize all accounts.
  5. Leave unrelated permissions unset. In particular, do not use the Global API Key or grant DNS, zone, Access, Workers, or account-administration permissions for this deployment-only token.
  6. Optionally set a token expiry and, where GitHub Actions runner IP addresses can be managed reliably, an IP filter. Continue to the summary, confirm the scope, then select Create Token.
  7. Copy the generated token immediately. Cloudflare displays its secret value only once. Do not save it in source control, a local .env file, workflow logs, or plaintext notes.
  8. In GitHub, open Settings > Secrets and variables > Actions > Secrets, select New repository secret, name it CLOUDFLARE_API_TOKEN, and paste the token value.

After saving the token, trigger a default-branch book workflow run. A token with the correct account scope and Cloudflare Pages: Edit permission allows the Wrangler action to deploy the _book artifact without any interactive Cloudflare login.

Cloudflare Access configuration

Create Access applications in the Cloudflare Zero Trust dashboard before sharing the site.

  1. Go to Zero Trust > Access > Applications and add a Self-hosted application for the production custom hostname, such as docs.internal.ringfinity.example.
  2. Add an allow policy limited to Mark, Will, and Reuben. Prefer a Ringfinity identity-provider group containing only those three users; otherwise use an explicit allow list of their identity-provider email addresses. Do not use an Everyone allow rule.
  3. Create a second application that covers preview hostnames. Use the appropriate wildcard hostname for the Pages project, or attach preview deployments to a protected internal wildcard domain.
  4. Test with an unauthenticated browser session: the production site and a preview hostname must redirect to Access before any documentation is served.
  5. Test with an allowed Ringfinity identity: the user should complete the identity-provider flow and reach the documentation.

Protecting only the custom production hostname is insufficient when the generated Pages hostnames remain reachable. Ensure the production URL and preview aliases receive an Access policy, or disable any unneeded public hostnames through the Cloudflare project configuration.

Operational checks

After changing the workflow or Cloudflare settings, verify:

  • The default-branch (RHIZA) BOOK run has successful book and Deploy book to Cloudflare Pages jobs.
  • The GitHub Actions summary reports the intended project name and URLs.
  • The Pages deployment serves the current commit.
  • Unauthenticated requests to production and preview URLs are challenged by Cloudflare Access.
  • An approved Ringfinity identity can open the documentation.

If deployment fails with an authentication or account error, recheck the account ID and the API token's account scope and Cloudflare Pages: Edit permission. If Project not found appears, create the Pages project or correct CLOUDFLARE_PAGES_PROJECT. If the book job succeeds but the Cloudflare job does not start, confirm that the push was to the default branch.