Skip to content
Sanmopia Modernization

Cloudflare Pages docs publishing

Switch to normal mode

Assembly Starlight docs deploy to public Cloudflare Pages through Cloudflare’s official Direct Upload with continuous integration path. GitHub Pages is not a Sanmopia docs target.

Workflow

Section titled “Workflow”

Workflow file: .github/workflows/docs-pages.yml.

The workflow runs on GitHub-hosted Ubuntu and follows Cloudflare’s documented GitHub Actions shape:

  1. Install with pnpm install --frozen-lockfile.
  2. Check docs with pnpm docs:check.
  3. Build Starlight with pnpm docs:build.
  4. Deploy apps/docs/dist with cloudflare/wrangler-action@v3.
  5. Remove the legacy Cloudflare Access application if it still exists for the docs host.

No Docker image is built for docs publishing, so BuildKit is not used on this path. If docs later need an OCI artifact, the image build must move through the shared Kubernetes BuildKit plane described in /home/devuser/work/fractalops/BUILDKIT_REMOTE_USAGE.md.

Bootstrap

Section titled “Bootstrap”

The Cloudflare Pages project is created once before CI deploys. Use either Cloudflare Pages Git integration in the dashboard or Wrangler Direct Upload project creation. Do not create the Pages project on every deploy.

Terminal window
CLOUDFLARE_ACCOUNT_ID=... CLOUDFLARE_API_TOKEN=... pnpm exec wrangler pages project create sanmopia-modernization-docs --production-branch main

Production URL after the first successful deployment:

https://sanmopia-modernization-docs.pages.dev

Public Access

Section titled “Public Access”

SANMOPIA_DOCS_PUBLIC_HOST is public. The workflow runs the Access cleanup script in public mode so an older Zero Trust Access application does not keep blocking the Pages host.

Do not re-enable Cloudflare Access for docs without a new explicit decision. If docs need restricted content later, move that content behind the application API or publish it in a separate protected project instead of re-protecting the general architecture docs.

Repository Secrets

Section titled “Repository Secrets”

Required GitHub Actions secrets:

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID

Recommended token permissions:

  • Account, Cloudflare Pages: Edit
  • Access: Apps and Policies Write, while the cleanup step still deletes the legacy docs app

Do not commit token values in docs, workflows, or env examples. If a token is pasted into chat or logs, rotate it and replace CLOUDFLARE_API_TOKEN.

Repository Variables

Section titled “Repository Variables”

Optional GitHub Actions variables:

  • CLOUDFLARE_PAGES_PROJECT_NAME, default sanmopia-modernization-docs
  • SANMOPIA_DOCS_PUBLIC_HOST, default sanmopia-modernization-docs.pages.dev
  • CLOUDFLARE_ACCESS_APP_NAME, default Sanmopia Modernization Docs
  • CLOUDFLARE_ACCESS_POLICY_NAME, default Allow yamon.io accounts
  • CLOUDFLARE_ACCESS_SESSION_DURATION, default 24h

Use a custom *.yamon.io host only after the Cloudflare Pages custom domain is attached to the Pages project. Cloudflare documents that a CNAME alone is not enough for Pages custom domains.

Manual Commands

Section titled “Manual Commands”
Terminal window
pnpm install --frozen-lockfile
pnpm docs:check
pnpm docs:build
CLOUDFLARE_ACCOUNT_ID=... CLOUDFLARE_API_TOKEN=... pnpm docs:deploy:cloudflare
CLOUDFLARE_ACCOUNT_ID=... CLOUDFLARE_API_TOKEN=... pnpm docs:access:public

Official References

Section titled “Official References”
  • Cloudflare Pages Direct Upload with CI: https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/
  • Cloudflare Pages Git integration: https://developers.cloudflare.com/pages/configuration/git-integration/
  • Cloudflare Access applications API: https://developers.cloudflare.com/api/resources/zero_trust/subresources/access/subresources/applications/