pnpm monorepo CI/CD設定ガイド【完全版】

Cloudflare Pages 自動デプロイ完了 プレビューURL発行

⚠ API_TOKENのみでは 404 エラー → 2つ必須

Cloudflare Pages への自動デプロイを GitHub Actions から実行するには、CLOUDFLARE_ACCOUNT_ID と CLOUDFLARE_API_TOKEN の2つを GitHub Secrets に登録することが前提条件です。API トークンだけを設定した状態でデプロイを実行すると、404 エラーで失敗します。この挙動は Cloudflare 公式ドキュメント（Cloudflare Pages / CI/CD integration）にも明記されており、初回セットアップで最もつまずきやすいポイントです。

CLOUDFLARE_ACCOUNT_IDとAPIトークンの取得・GitHub Secrets登録

Q：CLOUDFLARE_ACCOUNT_ID はどこで確認できますか？
A：Cloudflare ダッシュボードにログイン後、右サイドバーの「Account ID」欄に 32 桁の文字列として表示されます。URL にも含まれており、dash.cloudflare.com/ の形式でも確認できます。

Q：API トークンの権限スコープはどこまで必要ですか？
A：Cloudflare Pages へのデプロイのみを目的とする場合は、「Cloudflare Pages: Edit」権限だけで十分です。過剰なスコープを付与しないことがセキュリティ上のベストプラクティスです。

GitHub Secrets への登録手順は次のとおりです。

1. Cloudflare ダッシュボードの右サイドバーから Account ID をコピーする
2. 「My Profile」→「API Tokens」→「Create Token」を開き、Cloudflare Pages: Edit テンプレートを選択してトークンを発行する
3. GitHub リポジトリの「Settings」→「Secrets and variables」→「Actions」→「New repository secret」から以下の2つを登録する

• CLOUDFLARE_ACCOUNT_ID：手順1でコピーした Account ID
• CLOUDFLARE_API_TOKEN：手順2で発行したトークン

cloudflare/pages-actionの正しい設定方法と注意点

公式の cloudflare/pages-action@v1 を使う場合、directory（ビルド成果物のパス）の指定が必須です。directory を省略または誤指定すると、空のディレクトリがデプロイされ、本番で真っ白なページが公開されます。gitHubToken を渡すと、プルリクエスト上にプレビュー URL が自動表示され、レビューフローが大幅に改善されます。

- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    projectName: yarutoko          # Cloudflare Pages のプロジェクト名
    directory: packages/yarutoko/dist  # ビルド成果物のパス（要確認）
    gitHubToken: ${{ secrets.GITHUB_TOKEN }}
    wranglerVersion: '3'           # wrangler v3 を明示指定

projectName は Cloudflare ダッシュボードの Pages プロジェクト名と完全一致させる必要があります。大文字・小文字も区別されるため、ダッシュボードからコピーして貼り付けるのが確実です。

monorepo複数パッケージの差分デプロイ設計

lifeevent-tools のような pnpm monorepo 構成では、変更のあったパッケージのみをビルド・デプロイする設計が必要です。全パッケージを毎回デプロイすると CI 時間とコストが無駄になります。pnpm --filter でビルド対象を絞り込み、GitHub Actions の paths フィルタで発火条件を制御する2段構えが実務上のベストプラクティスです。

on:
  push:
    branches: [main]
    paths:
      - 'packages/yarutoko/**'
      - 'packages/lifeevent-hub/**'  # 依存 shared パッケージも監視

jobs:
  deploy-yarutoko:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile

      # 依存する shared パッケージを先にビルド（順序厳守）
      - run: pnpm --filter lifeevent-hub build

      # アプリ本体をビルド
      - run: pnpm --filter yarutoko build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: yarutoko
          directory: packages/yarutoko/dist
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

新しいパッケージを monorepo に追加した場合は、paths フィルタと --filter 指定の両方に追記が必要です。この2箇所の同期を忘れると、コードを変更したのにデプロイが走らない、または意図しないパッケージのデプロイが発火するという問題に発展します。変更時はセットで確認する運用ルールをチーム内で決めておくと安全です。

pnpm monorepo CI/CDで詰まるポイントと解決策

pnpm setup install / cache build order deploy secrets

! ! !

詰まり①② 詰まり④⑤ 詰まり③⑥ GitHub Actions — pnpm monorepo CI/CD 詰まりポイント分布

Q: 最初にハマったのはどこでしたか？
最初の壁は pnpm のセットアップそのものでした。actions/setup-node だけでワークフローを走らせると、即座に次のエラーが出ます。

sh: pnpm: not found
Error: Process completed with exit code 127.

原因は actions/setup-node が Node.js しか導入しないためです。pnpm を使うには pnpm/action-setup を別途追加し、さらに package.json に "packageManager": "pnpm@9.x.x" を記載する必要があります。この2点がセットでなければ、corepack が有効な環境では別のエラー（ERR_PNPM_NO_PKG_MANAGER_INSTALLED）も発生します。

# ワークフロー冒頭に必ず両方を記載する
- uses: pnpm/action-setup@v4
  with:
    version: 9
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'pnpm'

Q: Cloudflare Pages へのデプロイで「404」が出た経験はありますか？
あります。CLOUDFLARE_API_TOKEN だけを GitHub Secrets に登録してデプロイを走らせると、次のエラーで止まります。

✘ [ERROR] A request to the Cloudflare API failed.
  GET .../accounts/undefined/pages/projects/...
  [code: 7003] Could not route to /accounts/undefined/pages/projects

wrangler は CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID の両方を必要とします。Account ID はCloudflare ダッシュボードの右サイドバー「Account ID」欄から取得し、CLOUDFLARE_ACCOUNT_ID という名前でリポジトリの Secrets に登録します。公式の「Get started」ガイドにはトークンの取得手順しか目立って書かれておらず、Account ID は見落としやすい箇所です。

Q: monorepo 特有の詰まりはありましたか？
shared パッケージへの依存順序は一番気づきにくい問題でした。packages/shared に型定義やユーティリティを置いている構成では、ビルド前にそのパッケージが存在しない状態でアプリをビルドしようとして次のエラーが出ます。

Cannot find module '@lifeevent/shared'
Module not found: Error: Can't resolve '@lifeevent/shared/utils'

解決策は、ワークフロー内でビルドステップを依存関係の順に明示的に分割することです。pnpm --filter shared build を先に実行し、その後に pnpm --filter yarutoko build を走らせます。pnpm -r build のような再帰実行はトポロジカルソートを行いますが、Workspace の依存宣言（workspace:*）が正しく書かれていないと順序が保証されないため、CI では明示的な順序指定が安全です。

下表に6大詰まりポイントを原因・エラー・解決コマンドのセットでまとめます。

⑤のロックファイル不整合は「ローカルでは動くのに CI だけ落ちる」典型パターンです。pnpm install をローカルで実行した際に pnpm-lock.yaml の更新をコミットし忘れると、--frozen-lockfile オプションによって CI が意図通り失敗します。これは CI の正常動作であり、ロックファイルをプッシュすれば解消します。⑥はエラーメッセージが出ない分だけ発見が遅れます。act（GitHub Actions のローカル実行ツール）で事前検証する運用を入れると、プッシュ前に気づけます。

本番運用で役立つGitHub Actionsベストプラクティス

「CI/CDが動いた」から「本番で壊れない運用ができている」への距離は、意外と短い。pnpm monorepo GitHub Actions CI/CD 設定を通じて実際に詰まりを経験したエンジニアへのヒアリングでは、以下の3点が「後から追加したのではなく、最初から入れておけばよかった」設定として繰り返し挙がった。

① concurrencyで二重デプロイを防ぐ

Q: 本番稼働後に最初に当たったトラブルは何でしたか？
A: 同じブランチへ連続でプッシュしたとき、前のデプロイジョブが走ったまま次のジョブが始まって、Cloudflare Pages上の状態が壊れました。concurrencyを入れていなかったのが原因です。

concurrencyキーにcancel-in-progress: trueを指定すると、同じグループのジョブが実行中に新しいトリガーが入ったとき、古いジョブを自動キャンセルします。グループキーにgithub.refを含めることで、mainブランチとfeature/*ブランチが互いにキャンセルし合わない点も重要です。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

② セキュリティを考慮したシークレット管理パターン

Q: CLOUDFLARE_ACCOUNT_IDの管理はどうしていましたか？
A: 最初はリポジトリシークレット1か所にまとめていましたが、本番とプレビューで使うトークンを分けるためEnvironmentシークレットに移行しました。スコープが明確になってレビューもしやすくなりました。

GitHubのシークレット管理には2段階あります。全ワークフロー共通の値はRepository secrets、production/previewなどデプロイ先ごとに分けたい値はEnvironment secretsに登録します。CloudflareのAPIトークンは「Cloudflare Pages: Edit」権限だけを持つスコープ限定トークンを発行し、Account全体への書き込みは与えないのが最小権限の原則に沿った運用です。

• Repository secrets：Slack Webhook URLなど環境を問わない共通値
• Environment secrets：CLOUDFLARE_API_TOKEN・CLOUDFLARE_ACCOUNT_IDなど環境依存の値
• permissions キー：ワークフロー側でもcontents: readなどスコープを明示する

permissions:
  contents: read
  deployments: write

env:
  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

③ デプロイ失敗時のSlack通知設定

Q: 失敗に気づくまでどのくらいかかりましたか？
A: 通知を入れていなかった頃は、数時間後に本番サイトを確認して初めて気づくことがありました。if: failure()でSlack通知を入れてからは即時で検知できています。

slackapi/slack-github-actionとif: failure()の組み合わせが最短の実装経路です。通知文にgithub.run_idを埋め込んでActionsのログURLを直リンクにしておくと、Slackから一クリックで原因調査に入れます。成功通知を省いて失敗時だけ飛ばすことで、通知疲れを防ぐバランスも取れます。

- name: Notify Slack on failure
  if: failure()
  uses: slackapi/slack-github-action@v2
  with:
    payload: |
      {
        "text": "❌ Deploy failed: ${{ github.repository }} @ ${{ github.ref_name }}\n${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

この3点——concurrencyによる競合排除、Environmentシークレットによるスコープ分離、失敗時限定のSlack通知——は、monorepo 自動デプロイ構成の安定稼働に直結する設定です。ワークフローの動作確認が取れた直後に追加するのが、後から修正コストをかけない最適なタイミングといえます。

まとめ：pnpm monorepo CI/CD設定を成功させるポイント

この記事では、lifeevent-toolsのようなpnpm workspace構成のmonorepoをGitHub ActionsでCloudflare Pagesに自動デプロイする手順を、実際に詰まった経験をもとに整理した。設定の核心は3点に集約される。pnpm/action-setupの追加とpackageManagerフィールドの記載、CLOUDFLARE_ACCOUNT_IDを含むシークレットの両方登録、そしてsharedパッケージを先行ビルドするための--filterによるビルド順制御だ。

「なぜCLOUDFLARE_API_TOKENだけではデプロイが通らなかったのか」——wranglerのCLIは内部でAccount IDを参照してプロジェクトを特定するため、APIトークンが正しくてもCLOUDFLARE_ACCOUNT_IDが未設定だと404エラーで止まる。Cloudflareの公式ドキュメント（Cloudflare Workers / Pages — Environment Variables）にも両方の環境変数が必要と明記されており、CI設定時の確認漏れが最も多いポイントといえる。

デプロイ前チェックリスト

• ルートのpackage.jsonに"packageManager": "pnpm@x.x.x"が記載されているか
• pnpm/action-setupがactions/setup-nodeより前のステップに配置されているか
• GitHub EnvironmentsシークレットにCLOUDFLARE_API_TOKENとCLOUDFLARE_ACCOUNT_IDの両方が登録されているか
• 依存するsharedパッケージのビルドを--filter shared buildで先行実行しているか
• デプロイ対象のアプリを--filter で限定しているか

次に試せる発展的な設定

ワークフローが安定稼働したら、以下を追加すると運用品質が上がる。特に大規模なmonorepoでは、差分検知によるCI時間の短縮効果が大きい。

1. 差分デプロイの導入：dorny/paths-filterで変更のあったパッケージのみをビルド対象にする。変更のないパッケージのCIをスキップでき、実行時間を削減できる。
2. pnpm storeのキャッシュ設定：actions/cacheで~/.pnpm-storeをキャッシュする。GitHub Actionsの公式事例では依存インストールステップを40〜60%短縮できると報告されている。
3. Preview URLのPR自動コメント：cloudflare/pages-actionのgitHubTokenオプションを設定すると、PRにデプロイ先のPreview URLが自動的にコメントされ、レビューとデプロイ確認を一元化できる。