Cloudflare Access 認証付きドキュメント公開¶

概要¶

GitHub Pages のサイトを Cloudflare Pages にミラーし、Cloudflare Access で認証をかけることで、許可されたユーザーのみがドキュメントを閲覧できるようにします。

graph LR
    A[main push] -->|deploy.yml| B[gh-pages 更新]
    B -->|workflow_run| C[cloudflare-mirror]
    C -->|wrangler| D[Cloudflare Pages]
    D --> E[Cloudflare Access]
    E -->|認証済み| F[閲覧可能]
    E -->|未認証| G[ブロック]

既存の GitHub Pages デプロイ (deploy.yml → mike → gh-pages) はそのまま維持されます。

アーキテクチャ¶

レイヤー	役割	変更
`deploy.yml`	main → mike → gh-pages	変更なし
`cloudflare-mirror-from-gh-pages.yml`	gh-pages → Cloudflare Pages	新規追加
Cloudflare Pages	静的サイトホスティング	Dashboard で作成
Cloudflare Access	認証ゲートウェイ	Dashboard で設定

トリガーの仕組み

deploy.yml は GITHUB_TOKEN で gh-pages へ push しますが、 GITHUB_TOKEN による push は他のワークフローをトリガーしません（GitHub の仕様）。そのため cloudflare-mirror は workflow_run イベントで deploy.yml の完了を検知して起動します。ローカルから mike deploy --push した場合は通常の push トリガーで起動します。

セットアップ手順¶

Step 1: Cloudflare Pages プロジェクト作成¶

Cloudflare Dashboard にログイン
左メニュー → Workers & Pages → Create
Pages タブ → Direct Upload を選択（Git 連携は不要）
プロジェクト名を入力（例: aegis-docs）
空のディレクトリをアップロードして初期プロジェクトを作成
作成後、プロジェクト名をメモ → CLOUDFLARE_PAGES_PROJECT に使用

カスタムドメイン

Cloudflare Pages はデフォルトで <project-name>.pages.dev の URL が割り当てられます。独自ドメインを使いたい場合は、Pages の Custom domains から追加してください。

Step 2: Cloudflare API トークン作成¶

Cloudflare API Tokens にアクセス
Create Token → Custom token を選択
設定:

項目	値
Token name	`aegis-docs-deploy`
Permissions	Account / Cloudflare Pages / Edit
Account Resources	対象アカウントを選択

Continue to summary → Create Token
トークンをコピー → CLOUDFLARE_API_TOKEN に使用

トークンは一度しか表示されません

作成直後にコピーしてください。紛失した場合は再作成が必要です。

Step 3: Account ID 確認¶

Cloudflare Dashboard のトップページ
右サイドバーの Account ID をコピー
→ CLOUDFLARE_ACCOUNT_ID に使用

Step 4: GitHub Secrets/Variables 設定¶

リポジトリ: ryofukutani/aegis-docs

GitHub リポジトリ → Settings → Secrets and variables → Actions
以下を設定:

種別	名前	値	必須
Secret	`CLOUDFLARE_API_TOKEN`	Step 2 で作成したトークン	Yes
Secret	`CLOUDFLARE_ACCOUNT_ID`	Step 3 の Account ID	Yes
Variable	`CLOUDFLARE_PAGES_PROJECT`	Step 1 のプロジェクト名	Yes

Secret vs Variable

Secret: 暗号化され、ログに表示されない（API トークン、Account ID）
Variable: 平文だがログに表示可能（プロジェクト名は機密ではない）

Step 5: Cloudflare Access 設定¶

Cloudflare Zero Trust にアクセス
左メニュー → Access → Applications → Add an application
Self-hosted を選択
設定:

項目	値
Application name	`AEGIS Docs`
Session Duration	24 hours（推奨）
Application domain	`<project-name>.pages.dev` またはカスタムドメイン
Path	（空 = 全パス）

Next → Access Policy 作成:

項目	値
Policy name	`Team members`
Action	Allow
Include rule	Emails — 許可するメールアドレスを列挙

認証方法の選択

Email OTP (デフォルト): メールアドレスにワンタイムコードを送信。最も手軽
GitHub OAuth: GitHub アカウントで認証。Organization メンバーシップで制御可能
Google Workspace: Google アカウントで認証。ドメイン単位で制御可能

Save で完了

動作確認¶

自動デプロイの確認¶

main ブランチに docs 変更を push
GitHub Actions → Deploy Documentation が実行 → gh-pages が更新
GitHub Actions → Mirror to Cloudflare Pages が自動起動
Cloudflare Pages のデプロイ履歴に新しいデプロイが表示される

認証の確認¶

ブラウザのシークレットモードで https://<project-name>.pages.dev にアクセス
Cloudflare Access のログイン画面が表示される
許可されたメールアドレスでログイン → ドキュメントが表示される
許可されていないメールアドレス → ブロックされる

トラブルシューティング¶

Workflow が起動しない¶

GitHub Actions → Actions タブで Mirror to Cloudflare Pages が表示されているか確認
Deploy Documentation が成功完了しているか確認（workflow_run は成功時のみ起動）
ローカルから mike deploy --push した場合は push トリガーで起動する
手動実行: Actions タブ → Mirror to Cloudflare Pages → Run workflow で手動起動可能
Secrets/Variables が正しく設定されているか確認（エラーメッセージに不足項目が表示される）

Cloudflare Pages デプロイが失敗する¶

Error: Authentication error

→ CLOUDFLARE_API_TOKEN の権限を確認。Cloudflare Pages / Edit が必要

Error: Project not found

→ CLOUDFLARE_PAGES_PROJECT のプロジェクト名が正しいか確認

Access ログイン後に 404¶

Cloudflare Pages のデプロイが完了しているか確認
Application domain が Pages の URL と一致しているか確認

セキュリティ考慮事項¶

リスク	対策
API トークン漏洩	GitHub Secrets で暗号化保存。ログに表示されない
未認証アクセス	Cloudflare Access で全パスをブロック
GitHub Pages 側の公開	Private repo のため GitHub Pages は GitHub ユーザーのみ閲覧可能
トリガーループ	`cloudflare-mirror` は `gh-pages` を read-only で checkout。git push しないためループしない

ワークフロー構成図¶

リポジトリ: ryofukutani/aegis-docs

  main branch
    │
    ├── push (docs変更)
    │     └── deploy.yml
    │           ├── mike deploy --push dev     (main push時)
    │           └── mike deploy --push X.Y.Z   (tag push時)
    │                 │
    │                 ▼
    │           gh-pages branch (更新)
    │
    │   deploy.yml 完了 ─── workflow_run トリガー ───┐
    │                                                │
    │                                                ▼
    │                         cloudflare-mirror-from-gh-pages.yml
    │                               ├── checkout gh-pages (read-only)
    │                               └── wrangler pages deploy .
    │                                     │
    │                                     ▼
    │                               Cloudflare Pages
    │                                     │
    │                                     ▼
    │                               Cloudflare Access (認証)
    │                                     │
    │                                     ▼
    │                               ユーザー閲覧
    │
    └── tag push (vX.Y.Z)
          └── deploy.yml (同上)

  ローカルから mike deploy --push した場合:
    gh-pages push → cloudflare-mirror (push トリガー) → Cloudflare Pages