Skip to content

Engineering docs site — Cloudflare Pages + Access

The engineering docs (this mkdocs site) are published to Cloudflare Pages and gated by Cloudflare Access so only @raklet.org identities can read them. This replaces GitHub Pages, which is public on our plan and previously leaked the docs.

The build/deploy is automated in .github/workflows/docs.yml. The one-time Cloudflare setup below is manual (dashboard + secrets). Until it is done, the workflow builds the docs and skips the deploy (no failure).

The deploy step is harmless without Access, but the site is not private until the Access policy in step 4 exists. Do step 4 before (or together with) step 3.

One-time setup

1. Create the Pages project

Cloudflare dashboard → Workers & Pages → Create → Pages → Direct Upload. Name it exactly raklet-eng-docs (matches --project-name in the workflow). You can upload an empty folder to finish creation; the workflow does real deploys.

2. Create an API token + find the Account ID

  • Account ID: Workers & Pages → right sidebar → Account ID.
  • API token: My Profile → API Tokens → Create Token → template “Cloudflare Pages — Edit” (or a custom token with Account › Cloudflare Pages › Edit). Scope it to the one account. Copy the token once.

3. Add the GitHub repo secrets

Repo → Settings → Secrets and variables → Actions → New repository secret:

Secret Value
CLOUDFLARE_API_TOKEN the token from step 2
CLOUDFLARE_ACCOUNT_ID the account id from step 2

Once CLOUDFLARE_API_TOKEN exists, the next push to master touching docs/** (or a manual Run workflow) deploys the site.

4. Gate it with Cloudflare Access (this is what makes it private)

Cloudflare Zero Trust → Access → Applications → Add an application → Self-hosted:

  • Application domain: the Pages production hostname — raklet-eng-docs.pages.dev (and your custom domain too, if you add one in step 5). Cover every hostname the site answers on, or that hostname stays public.
  • Policy: Action Allow, rule Emails ending in @raklet.org (or your Google Workspace / OTP identity provider). Add a second Allow rule for any external reviewers as needed.
  • Leave the default “block everyone else”.

Verify in an incognito window: hitting the site should now show the Cloudflare Access login, not the docs.

5. (Optional) Custom domain

Pages project → Custom domains → add e.g. docs.raklet.org (needs the zone in Cloudflare DNS). Then add that hostname to the Access application from step 4.

Notes

  • Cloudflare Access is free for up to 50 seats — fine for the team.
  • The workflow deploys --branch=master (production). PRs build but do not deploy.
  • No secrets live in this repo; the token is only a GitHub Actions secret.
  • If you ever retire this, also remove the CLOUDFLARE_* secrets and the Access app.