コンテンツにスキップ

Cloudflare Pages + Access Runbook

更新日: 2026-07-05

private repository のまま HTML ドキュメントを公開し、閲覧者を Cloudflare Access で制限するための手順である。GitHub Pages は使わず、GitHub Actions で docs/ をビルドし、Cloudflare Pages に direct upload する。

前提

  • Cloudflare アカウントを持っている。
  • Cloudflare Pages project を作成済みである。
  • 公開したい URL を Access で保護できる。まずは *.pages.dev の preview/production URL でもよい。

Repository 側

Cloudflare Pages は MkDocs preset を持っており、build output は site を使う。この repository では docs 依存も pyproject.toml の dependency group と uv.lock で管理する。

ローカルで通常の build を確認する場合:

mise run docs:build

Cloudflare Pages と同じ uv ベースの build を確認したい場合:

uv sync --group docs --frozen
uv run --group docs mkdocs build --strict

Cloudflare Pages Project

Cloudflare dashboard で Pages project を作る。GitHub Actions から direct upload するため、Cloudflare 側の build command は使わない。

Setting Value
Project type Pages
Upload method Direct Upload
Project name GitHub variable CLOUDFLARE_PAGES_PROJECT_NAME と同じ値
Build output directory site

*.workers.dev の URL は Worker project 側の URL であり、wrangler pages deploy の deploy 先ではない。 pages deploy を使う場合は、Cloudflare dashboard の Workers & Pages で Pages project として作成されている必要がある。

Wrangler で Pages project を作る場合:

CLOUDFLARE_ACCOUNT_ID=YOUR_ACCOUNT_ID \
  CLOUDFLARE_API_TOKEN=YOUR_API_TOKEN \
  npx wrangler pages project create YOUR_PROJECT_NAME --production-branch=main

例:

CLOUDFLARE_ACCOUNT_ID=YOUR_ACCOUNT_ID \
  CLOUDFLARE_API_TOKEN=YOUR_API_TOKEN \
  npx wrangler pages project create pokemon-card-ai-docs --production-branch=main

この例では GitHub variable も同じ値にする。

CLOUDFLARE_PAGES_PROJECT_NAME=pokemon-card-ai-docs

Cloudflare の公式 docs では、Pages は Wrangler による prebuilt assets の direct upload をサポートしている。この repository では GitHub Actions の .github/workflows/docs-cloudflare-pages.yml が site/ を upload する。

GitHub Actions Secrets

GitHub repository の Settings > Secrets and variables > Actions に次を設定する。

Type Name Value
Secret CLOUDFLARE_API_TOKEN Cloudflare Pages Edit 権限を持つ API token
Secret CLOUDFLARE_ACCOUNT_ID Cloudflare account ID
Variable CLOUDFLARE_PAGES_PROJECT_NAME Cloudflare Pages project name

API token は Cloudflare dashboard の API Tokens から作成する。Cloudflare 公式 docs では Account / Cloudflare Pages / Edit permission が案内されている。

GitHub Actions Deploy

main に docs 関連変更を push すると、docs-cloudflare-pages workflow が動く。

  1. uv sync --group docs --frozen で docs dependency を同期する。
  2. uv run --group docs mkdocs build --strict で site/ を生成する。
  3. cloudflare/wrangler-action@v3 で Wrangler 4 系を使い、pages deploy site を実行する。

手動で再実行したい場合は GitHub Actions の docs-cloudflare-pages から Run workflow を使う。

Cloudflare Access

Pages deployment ができたら、Zero Trust で Access application を作る。

  1. Cloudflare dashboard で Zero Trust を開く。
  2. Access > Applications から application を追加する。
  3. Application type は self-hosted を選ぶ。
  4. Application domain に Pages の production URL、または custom domain を設定する。
  5. Policy で許可したい email、domain、GitHub organization などを指定する。
  6. 未認証ユーザーで URL を開き、Cloudflare Access の login 画面にリダイレクトされることを確認する。
  7. 許可ユーザーで login し、MkDocs の top page と navigation が読めることを確認する。

確認ポイント

  • GitHub Actions の docs-cloudflare-pages が green である。
  • Cloudflare Pages の deployment が green である。
  • site/index.html が生成されている。
  • Architecture、Modules、Operations の navigation が表示される。
  • 未認証アクセスでは本文が見えず、Access login が出る。
  • 許可ユーザーだけが閲覧できる。

運用

  • docs を更新したら main へ push すると GitHub Actions から Cloudflare Pages に自動 deploy する。
  • preview deployments も必要なら Access policy の対象 domain に含める。
  • GitHub Actions 側の build が失敗したら、まず mise run docs:build、pyproject.toml の docs dependency group、uv.lock を確認する。
  • deploy が失敗したら、CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID、 CLOUDFLARE_PAGES_PROJECT_NAME を確認する。
  • Wrangler 3.90.0 が install される場合は古い default に寄っているため、workflow の wranglerVersion: "4" が入っていることを確認する。
  • The Pages project "<name>" does not exist. が出る場合は、Cloudflare 側に同名の Pages project が存在しない。Workers project では代用できないため、Pages project を作成して CLOUDFLARE_PAGES_PROJECT_NAME をその名前に合わせる。