NxまたはTurborepoによるモノレポのCI: 影響を受けるビルド
最終更新日
モノレポでは、1行の変更でalso全体を再ビルドおよび再テストする必要はありません。これを可能にする考え方は2つあります。変更の影響を受けたプロジェクトだけでタスクを実行すること、そして以前の実行結果をキャッシュから再利用することです。NxとTurborepoはどちらもこの両方を提供しています。このガイドでは、それぞれのGitHub Actionsのセットアップと、影響を受けたビルドを知らないうちに全体ビルドに戻してしまう間違いについて説明します。
「変更された部分だけ」を実現する3つのレベル
- ワークフローのトリガー。
pathsフィルターは、ワークフローそのものを開始するかどうかを決めます。 - 影響範囲の検出。 ツールは変更内容をベースコミットおよびプロジェクトグラフと比較し、変更されたファイルに依存するプロジェクトを選択します。
- タスクのキャッシュ。 選択されたタスクについて、ツールは入力をハッシュ化し、同じ入力を見たことがあれば結果を再生します。リモートキャッシュを使うと、その結果をCI実行と開発者の間で共有できます。
3つすべてを使用してください。それぞれ異なるケースに対応します。
ベースコミットを正しく設定する
影響範囲の検出には履歴が必要です。デフォルトのactions/checkoutは単一のコミットしか取得しないため、ツールが比較対象を持てません。完全な履歴を取得するか、十分な範囲の履歴を取得してください。
- uses: actions/checkout@v4
with:
fetch-depth: 0
ほとんどのリポジトリでは、完全な履歴を取得する方法が簡単で問題ありません。非常に大規模なリポジトリでは、マージベースが取得範囲に含まれている限り、より深さを限定したshallow fetch(例: fetch-depth: 50)も機能します。
プルリクエストでは、対象ブランチ(origin/main)と比較してください。mainへのpushでは、直前のコミットではなく、直前に成功した実行のコミットと比較してください。そうすれば、失敗した実行によって変更が見えなくなることを防げます。Nxにはこのためのアクションが用意されています。
- uses: nrwl/nx-set-shas@v4
これはNX_BASEとNX_HEADを、mainブランチで最後に成功した実行と現在のコミットに設定します。
Nxのセットアップ
name: ci
on:
pull_request:
push:
branches: [main]
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: nrwl/nx-set-shas@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx nx affected -t lint test build
nx affected -t lint test buildは、影響を受けたプロジェクトに対してのみ、依存関係の順序でそれらのターゲットを、ローカルキャッシュを使って実行します。このコマンドはNX_BASEとNX_HEADを読み取ります。小規模なランナーで並列数を制御したい場合は--parallel=3を追加してください。実行をまたいで結果を再利用するには、Nx Cloudまたは別のリモートキャッシュに接続してください。接続しない場合、CI実行ごとにローカルキャッシュは空の状態から始まります。
Turborepoのセットアップ
Turborepoのフィルター構文では、gitの変更によって対象を選択します。
- run: npx turbo run lint test build --filter="...[origin/main]"
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
...[origin/main]は「origin/main以降に変更されたパッケージと、それらに依存するすべてのパッケージ」を意味します。TURBO_TOKENとTURBO_TEAMを設定すると、Turborepoはリモートキャッシュを使用します(Vercelのものか、そのAPIを実装したセルフホスト型サーバーを利用できます)。リモートキャッシュを使わない場合は、ローリングキーを用いてactions/cacheでローカルの.turboディレクトリを保存できます。詳しくはキャッシュのガイドをご覧ください。
turbo.jsonでタスクの入力と出力を正確に定義してください。inputsが広すぎる場合(例: コミットごとに変わるファイルを含めている場合)、タスクは常にキャッシュミスになります。outputsにフォルダーが含まれていない場合、再生されたタスクは不完全な結果を生成します。
リモートキャッシュで得られるもの
キャッシュヒットが発生すると、作業は完全にスキップされ、ログとファイルが再生されます。1つのパッケージに触れる典型的なPRでは、そのパッケージに依存するパッケージだけが再ビルドされ、それ以外はすべてヒットします。効果が特に大きいのは次のような場合です。
- 複数のPRが同じコードパスに触れ、結果が共有される場合。
- 開発者のマシンとCIがキャッシュを共有し、CIがローカルでビルドされた結果を再生できる場合。
- タスクが決定的である場合。時刻、ネットワーク、乱数シードを読み取るタスクは、安全にキャッシュできません。
リモートキャッシュの認証情報はシークレットとして扱い、書き込み権限は信頼されたブランチに限定してください。キャッシュが改ざんされるとサプライチェーンのリスクになるため、フォークからのプルリクエストに書き込みを許可しないでください。詳しくはGitHub Actionsのセキュリティ対策をご覧ください。
トリガーフィルターの併用
ドキュメントサイトやインフラのコードなど、リポジトリの一部が無関係な場合は、ワークフローレベルで軽量なフィルタリングを行うと効果的です。
on:
pull_request:
paths:
- "apps/**"
- "packages/**"
- "package-lock.json"
- ".github/workflows/ci.yml"
ワークフローファイル自体とロックファイルは含めてください。ワークフローが必須チェックになっている場合、スキップされた実行は、そのチェックを永遠に「Expected」のままにします。これは、常に実行される要約ジョブを用意するか、ワークフロー内でパス検出を行うことで対処してください。
注意すべき点
- shallow cloneでは、ツールによって影響範囲が空になるか、全体になります。
- 共通ファイル(ルートの
package.json、ロックファイル、tsconfigなど)が変更されると、すべてのプロジェクトのハッシュが変わります。これは正しい動作ですが、無関係なファイルが共通の入力として登録されていないか確認してください。 - 暗黙の依存関係。たとえば、依存関係を宣言せずに、別のパッケージのスキーマファイルを読み込むサービスがある場合です。影響範囲の検出ではこれを見逃します。プロジェクトの設定で明示的に宣言してください。
- デプロイは、
mainや夜間実行における全体ビルドという安全網がなければ、影響範囲だけのビルドに頼るべきではありません。 - キャッシュサイズ: 保持期間を設定しない限り、リモートキャッシュは際限なく増え続けます。
効果を測定する
導入前後のPRにおけるCI時間の中央値と90パーセンタイルを追跡してください。あわせて、キャッシュから提供されたタスクの割合も追跡してください。1週間後もこの割合が約半分を下回ったままであれば、入力とベースコミットの設定を見直してください。節約された分数を月次の数値にするにはCI分数の予測ツールを使い、影響を受けたプロジェクトでもテストスイートの実行が長い場合はテストシャーディングの計画ツールを使ってください。
よくある質問
NxとTurborepoのどちらを選ぶか
どちらも影響範囲の実行とキャッシュに対応しています。Nxはより豊富なプロジェクトグラフ、ジェネレーター、分散タスク実行を備えています。Turborepoは軽量で、既存のnpmワークスペースへの追加が簡単です。キャッシュ以外に何が必要かで選んでください。
パスフィルターはまだ必要ですか
簡単なケースでは必要です。ランナーをまったく起動しなくて済むからです。より細かい判断はツールが担当します。
JavaScript以外のリポジトリでも機能しますか
Nxは複数の言語向けのプラグインを提供しています。また、Bazel、Pants、Gradleなどのツールにも独自のキャッシュと影響範囲の仕組みがあります。原則(ベースコミット、グラフ、キャッシュ)は共通です。
なぜすべてのPRで全体が影響を受けてしまうのですか
通常は、変更されたグローバルファイル、浅いチェックアウト、または誤ったベースSHAが原因です。nx show projects --affected で影響を受けるリストを出力して、デバッグしてください。
compiler.devの位置づけ
影響範囲のみのビルドは実行されるジョブ数を減らし、高速ランナーは各ジョブの所要時間を短縮します。compiler.devの比較モードでは、既存のワークフローをより高速なマシンで実行できるため、お使いのリポジトリで後者の効果を計測できます。
関連記事
- GitHub ActionsでTypeScriptモノレポを高速化するGitHub Actionsで TypeScriptモノレポの型チェックとリンターを高速化する: インクリメンタルtsc、プロジェクト参照、Lintキャッシュ、並列ジョブ
- GitHub ActionsでモノレポのPlaywrightを高速化するGitHub Actions で Node モノレポの Playwright E2E テストを高速化: アプリを一度だけビルドし、Web アプリに変更がないときは E2E をスキップし、シャーディングとレポートのマージを行います。
- GitHub ActionsでBazelモノレポを最速でCIするGitHub Actions での高速な Bazel CI。影響を受けるビルドのためのターゲット判定、リモートキャッシュのフラグ、PR からの読み取り専用アップロード、シャーディング、完全なワークフローを紹介します。
- GitHub ActionsでNxモノレポを最速でCIするGitHub Actions で Nx の CI を高速化。nx-set-shas を使った nx affected、Nx リモートキャッシュ、タスク分散、fetch-depth、完全なワークフローを紹介します。