Skip to main content

Branching and CI for this site

The documentation repo follows the same branch and deployment model as the frontend apps: develop is the integration branch and deploys to a dev URL on every push; main deploys to production.

BranchWorkflowCloudflare Pages branchURL
develop.github/workflows/deploy-develop.ymldevelop (preview)https://docs-dev.everymanawarrior.cc
main.github/workflows/deploy-production.ymlmain (production)https://docs.everymanawarrior.cc
pull requests.github/workflows/ci.ymlnonebuild and typecheck only

Pages project: emaw-documentation. Output directory: build/.

Day-to-day flow​

  1. Branch from develop (feature/<topic> or docs/<topic>).
  2. Edit pages under docs/, run npm run build locally. The build fails on broken internal links.
  3. Open a pull request into develop. The CI workflow builds it.
  4. Merge. The Deploy develop workflow publishes to docs-dev within a couple of minutes.
  5. When the dev site looks right, open a pull request from develop into main. Merging deploys production.
tip

For a typo or a small wording fix, the Edit this page link at the bottom of every page opens the file on GitHub. Commit to a new branch and open the pull request from there.

What the workflows do​

Each deploy workflow runs on ubuntu-latest with Node 24:

- run: npm ci
- run: npm run typecheck
- run: npm run build
- run: npx wrangler@4 pages deploy build --project-name emaw-documentation --branch develop
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

The develop build sets DOCS_URL=https://docs-dev.everymanawarrior.cc so Docusaurus bakes the right canonical URL and sitemap; production uses the default in docusaurus.config.ts.

Deploys are done with Wrangler from the workflow rather than Cloudflare's own Git integration, which keeps every frontend on one mechanism and lets the build run with the repo's Node version.

One-time setup (done in the Cloudflare and GitHub dashboards)​

These steps cannot be done from the repository. Ask the Cloudflare account owner (see who to ask).

1. Cloudflare Pages project​

  1. Cloudflare dashboard → Workers & Pages → Create → Pages → Direct Upload (not Git).
  2. Project name emaw-documentation. Production branch main.
  3. The first deploy can be an empty upload; the workflows take over from there.

2. Custom domains​

In the project → Custom domains:

  • docs.everymanawarrior.cc → production
  • docs-dev.everymanawarrior.cc → the develop branch preview

Cloudflare creates the DNS records in the everymanawarrior.cc zone automatically.

3. Cloudflare Access​

The docs are internal. In Zero Trust → Access → Applications → Add an application → Self-hosted:

  • Application domain: docs.everymanawarrior.cc and docs-dev.everymanawarrior.cc (two applications, or one with both domains).
  • Identity provider: the existing Google Workspace login.
  • Policy: Allow when Emails ending in @everymanawarrior.com.
  • Session duration: match the admin app.

Also protect the raw *.emaw-documentation.pages.dev preview hostnames or disable preview access in the Pages project so the site cannot be reached around Access.

4. API token and GitHub secrets​

  1. Cloudflare → My Profile → API Tokens → create a token with Cloudflare Pages: Edit on the account (reuse the token the other frontends use if your policy allows).
  2. GitHub repo → Settings → Environments: create develop and production. On production, restrict deployment branches to main.
  3. Add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID as environment secrets on both.

5. Verify​

Push to develop, watch Actions, then open https://docs-dev.everymanawarrior.cc. You should be asked to sign in with Google before the site loads.

Manual deploy​

If Actions is unavailable:

npx wrangler login
npm run build
npx wrangler pages deploy build --project-name emaw-documentation --branch develop

Use --branch main for production. Set DOCS_URL before npm run build when deploying develop by hand.