デプロイ

GitHub Actions CI/CDを使用してzudo-docサイトをCloudflare Workersにデプロイする。

概要

zudo-docは完全な静的サイトジェネレーターです。pnpm buildの出力はHTML、CSS、JavaScriptファイルのディレクトリであり、どこでもデプロイできます。デフォルトのデプロイ先はCloudflare Workers（静的アセット）で、CI/CDの自動化にはGitHub Actionsを使用します。

CIパイプラインは合計ビルド時間を短縮するために並列ジョブに分割されています。サイト生成とドキュメント履歴の抽出は独立したジョブとして実行され、デプロイ前にマージされます。

Cloudflare Workers静的アセット

ビルドされたサイトはwrangler deployを使用してデプロイされます。デプロイアーティファクトには以下が含まれます：

• zfbのビルド出力（dist/）

• 事前生成されたdocヒストリーJSONファイル（docHistoryが有効な場合）

• dist/_worker.js — CFアダプターが生成する明示的なメインエントリー

サイトはWorkers静的アセット層によりルート（base = "/"）で配信されます。動的ルート（例：/api/ai-chat）はdist/_worker.jsが処理し、それ以外のGETリクエストはdist/から静的アセットとして配信されます。

CIパイプラインの構造

プロジェクトでは3つのGitHub Actionsワークフローを使用します：本番デプロイ（main-deploy.yml）、PRチェックとプレビュー（pr-checks.yml）、ブランチプレビュー（preview-deploy.yml）。

本番環境（main-deploy.yml）

mainへのプッシュでトリガーされます。5つのジョブが実行されます：

1. build-site — フルクローン（fetch-depth: 0）、pnpm buildでzfbサイトをビルド（SKIP_DOC_HISTORYなし — preBuildステップがSSGメタブロックを生成するためにフルgit履歴が必要）

2. html-validate — ビルド済みdist/のHTMLエレメントエラーを検証

3. build-history — フルクローン（fetch-depth: 0）、@takazudo/zudo-doc-history-server generateを実行してすべてのコンテンツファイルのgit履歴を事前抽出

4. deploy — サイトと履歴のアーティファクトをマージし、wrangler deployで本番環境にデプロイ

5. notify — デプロイステータスをIFTTTウェブフックで通知

コンカレンシー: group: production-deploy, cancel-in-progress: false — 先行するデプロイはキャンセルされずに完了が許可されます。

PRチェック（pr-checks.yml）

mainを対象としたプルリクエストでトリガーされます。15のジョブが実行されます：

1. check-template-drift — ソースファイルとジェネレーターテンプレート間のドリフトを検証

2. check-pin-parity — @takazudo/zfbのピンがすべてのパッケージソース間で一致しているか確認

3. check-fixture-settings-drift — src/config/settings.tsのすべてのキーがe2eフィクスチャー設定ファイルに存在するか（またはアローリスト済みか）を確認

4. check-package-safelist — @takazudo/zudo-docパッケージ内のすべてのレスポンシブ・任意値ユーティリティクラスを生成済みのdist/safelist.cssがカバーしているか検証

5. check-b4push-ci-parity — scripts/run-b4push.shの軽量ガードゲートすべてに対応するCIジョブが存在するか確認

6. check-e2e-spec-naming — すべてのe2eスペックファイル名が既知のフィクスチャープレフィックスを使用しているか確認（Playwrightが確実に検出できるよう）

7. lint-gates — pnpm tags:audit --ciとpnpm lint:tokens（デザイントークンリント）を実行

8. typecheck — pnpm checkを実行（TypeScript型チェック）

9. package-tests — すべてのパッケージスコープのvitestスイートを実行

10. root-tests — ルートユニットテストスイートを実行

11. build-site — フルクローン（fetch-depth: 0）、pnpm build、その後check:links（SKIP_DOC_HISTORYなし — 本番と同じ理由：preBuildにSSGメタ日付のためのフルgit履歴が必要）

12. html-validate — ビルド済みdist/のHTMLエレメントエラーを検証

13. build-history — フルクローン、docヒストリーの生成

14. e2e — Playwrightエンドツーエンドテストを実行

15. preview — アーティファクトをマージしてwrangler versions upload --preview-aliasでプレビューをアップロード、PRコメントとしてURLを投稿

コンカレンシー: group: pr-checks-{pr-number}, cancel-in-progress: true — 古い実行はCIの消費を節約するためにキャンセルされます。

プレビューデプロイ

各PRはwrangler versions upload --preview-alias <alias>により安定したプレビューエイリアスURLを取得します（wrangler.tomlのpreview_urls = trueで有効化）。エイリアスはPRチェックではpr-<番号>、ブランチプレビューではブランチスラッグです。URLは*.workers.dev上にあり（本番のカスタムドメインではありません）、サブドメインはエイリアスで始まります：

https://<alias>-zudo-doc.<your-subdomain>.workers.dev

CIはwranglerの出力から正確なホストを解析し、previewジョブによってPRのコメントとして自動的に投稿されます。

SKIP_DOC_HISTORY

SKIP_DOC_HISTORY=1が設定されると、doc-historyのzfbプラグインはすべてのgit履歴呼び出しをスキップして空のマニフェストを書き出し、すべてのSSGページから作成日・更新日・著者ブロックが消えます。標準CIではbuild-siteジョブにこのフラグは設定されません — preBuildステップが実際の日付を生成するためにフルgitアクセスが必要なためです。

GEN_DOC_HISTORY

GEN_DOC_HISTORY=1（#1986で導入）はdoc-historyプラグインのpostBuildフックを制御します — dist/doc-history/にページごとのリビジョン／差分JSONを書き出し、DocHistoryドロップダウンアイランドに供給するステップです。プラグインのpreBuildフック（表示される作成日・更新日・著者のメタブロック）はこれに影響されず、SKIP_DOC_HISTORYのみで制御されます。postBuildは次の決定表に従います：

ジョブ間のデータ共有

ビルドアーティファクトはactions/upload-artifactではなく**actions/cache**を使用してジョブ間で共有されます。キャッシュキーはクロスラン汚染を防ぐためにgithub.run_idにスコープされています：

key: dist-${{ github.run_id }}
key: doc-history-${{ github.run_id }}

deploy（またはpreview）ジョブは両方のキャッシュを復元し、wrangler deploy（本番）またはwrangler versions upload（プレビュー）を呼び出す前にdist/ディレクトリをマージします。

必要なシークレット

リポジトリのSettings → Secrets and variables → Actionsで設定します：