GitHub ActionsでNxモノレポを最速でCIする
最終更新
最速の Nx CI は、3 つのことを行います。変更の影響を受けたプロジェクトだけを実行し(nx affected)、リモートキャッシュで結果を再利用し、残りの作業を複数のマシンに分散させます。このガイドでは、影響のある実行を静かに壊す Git の設定を含め、Nx と Turborepo の一般ガイドより詳しく Nx を解説します。
手順 1:影響のあるものだけを実行する
nx affected は 2 つのコミットを比較し、変更されたプロジェクト、または変更の影響を受けるプロジェクトに対してのみタスクを実行します。比較には基点(base)と先端(head)が必要です。nrwl/nx-set-shas アクションがこれらを自動的に算出します。
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
filter: tree:0
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build
nx-set-shas の README(2026 年 10 月確認)によると、このアクションはジョブ向けに NX_BASE と NX_HEAD を出力し、ステップの出力として base と head も公開します。プルリクエストでは、基点は main とのマージベースになります。main へのプッシュでは、ワークフローの実行が成功した直近のコミットになるため、失敗したコミットの変更が次の実行から隠れることはありません。見つからない場合は、error-on-no-successful-workflow: true を設定しない限り HEAD~1 にフォールバックします。
fetch-depth の要件
actions/checkout は、既定では 1 つのコミットだけを取得します。コミットが 1 つだけでは比較する基点がなく、nx affected はエラーになるか、すべてを影響ありとして扱います。nx-set-shas の README では、Nx が比較する基点を持てるようにすべてのブランチとコミットが必要とされているため、ワークフローでは fetch-depth: 0 を使用します。
filter: tree:0 を指定すると、blobless 形式の部分クローンになり、履歴全体を低コストで保てます。コミットのメタデータは先に取得し、ファイルの内容は必要になったときに取得します。大規模なリポジトリでは、1 分かかっていたものが数秒で済むことがよくあります。
既定の基点を変更する
Nx は nx.json の defaultBase(通常は main)も参照します。トランクブランチ名と一致させてください。一致させないと、影響のある実行が誤った参照と比較されます。
手順 2:リモートキャッシュ
ローカルキャッシュが役立つのは、同じランナーが同じファイルを参照する場合だけです。GitHub Actions では各ジョブがクリーンな状態から始まるため、実行、ブランチ、チームメンバーをまたいでタスクの出力を再利用するには、リモートキャッシュが必要です。
Nx のドキュメント(2026 年 10 月確認)では、npx nx-cloud onboard connect-workspace でワークスペースを接続し、nxCloudId を nx.json に書き込むとしています。CI の認証については、CI アクセストークンのガイドで読み取り専用と読み書き可能なアクセストークンが説明されています。フォークからのプルリクエストには読み取り専用トークンを、信頼できるブランチには読み書き可能トークンを使用してください。こうすると、信頼できないプルリクエストがキャッシュを汚染することを防げます。
ログでキャッシュヒットを確認します。キャッシュされたタスクは [local cache] または [remote cache] と表示され、コマンドを実行せずに出力を再生します。最後の概要に、キャッシュから読み取られたタスク数が表示されます。
Nx Cloud を使わない場合は、Nx のカスタムタスクランナーとキャッシュプラグインを通じて別のリモートキャッシュ実装を使えます。または、actions/cache で .nx/cache ディレクトリをキャッシュすることもできます。Actions キャッシュの方法は最も手軽に試せますが、制限が 2 つあります。PR のキャッシュはスコープが限定され、リポジトリの 10 GB の上限が適用されます。詳しくは キャッシュの制限 を参照してください。
- uses: actions/cache@v6
with:
path: .nx/cache
key: nx-${{ runner.os }}-${{ github.sha }}
restore-keys: |
nx-${{ runner.os }}-
手順 3:タスクを分散させる
影響範囲の限定とキャッシュを行っても、大規模なプルリクエストは遅いままのことがあります。Nx はタスクを複数のエージェントに分散できます。Nx CI の紹介(2026 年 10 月確認)では、その設定を .nx/ci-config.yaml で行い、インストールの前にワークフローでエージェントを起動します。
# .nx/ci-config.yaml
dte:
distribute-on: 3 linux-large-js
lifecycle:
stop-after:
- build
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
filter: tree:0
- run: npx nx-cloud start-workers
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build
先にワーカーを起動すると、メインのジョブが依存関係をインストールしている間に、ワーカーが起動を完了できます。キャッシュされ分散されるのは nx 経由で実行されたタスクだけです。そのため、npm test がテストランナーを直接呼び出すのではなく、nx test をラップしていることを確認してください。
プレーンな GitHub Actions を使いたい場合は、マトリクスを使って自分でシャーディングできます。Nx ではプロジェクト単位での分割に対応しており、単一の大きなテストスイートであれば、ランナー自体をシャーディングできます。詳しくは GitHub Actions でのテストシャーディング を参照してください。
まとめ
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
actions: read
contents: read
jobs:
main:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
filter: tree:0
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build --parallel=4
--parallelは、1台のマシン上で同時に実行するタスクの数を制御します。コア数が多ければ、この値を大きくできます。runs-onの行はcompiler.dev固有の唯一の部分で、ジョブを8 vCPUのマシンに移し、料金は1分あたり$0.008です。元に戻すには、この行を変更します。料金を参照してください。
影響範囲の限定が全体の実行になってしまう誤り
- 浅いチェックアウト。最もよくある誤りです。
fetch-depth: 0を使用してください。 - ルートのファイルの変更。
package-lock.json、nx.json、または共有の tsconfig を変更すると、すべてが影響を受けることになります。Nx のnamedInputsを使うと、各ターゲットが依存する範囲を絞り込めます。 - 基点が失敗したコミット。失敗した実行の後に
HEAD~1を使うと、失敗が隠れてしまいます。nx-set-shas は、最後に成功したコミットを選びます。 - Nx 以外のスクリプト。
nxを経由しないタスクは、キャッシュと影響範囲の判定をスキップします。 - 保存されないキャッシュ。信頼できるブランチがキャッシュを書き込むようにしてください。
インストールが遅い場合は、npm のキャッシュまたは pnpm のキャッシュを参照してください。他のモノレポツールについては、Turborepo と Bazel を参照してください。
よくある質問
nx affected は実際に何を比較しますか?
NX_BASE と NX_HEAD の間で変更されたファイルを、プロジェクトグラフを通してプロジェクトとその依存先に対応させたものです。
Nx Cloud は必要ですか?
影響範囲の限定だけであれば必要ありません。実行をまたいだ再利用には、リモートキャッシュか分散実行が必要です。Nx Cloud が公式にサポートされた方法です。.nx/cache に対する actions/cache は、制限のある代替手段です。
なぜ私のプルリクエストで nx affected がすべてを実行するのですか?
fetch-depth を確認してください。NX_BASE が NX_HEAD の祖先と予期しない関係になっていないかも確認してください。ルートの設定ファイルが変更されていないかも確認してください。
マージキューでも動作しますか?
nx-set-shas には、マージグループ用の use-previous-merge-group-commit 入力(既定値は true)があります。詳しくは GitHub のマージキュー を参照してください。
関連記事
- 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でpnpmワークスペースのCIを最速化するGitHub Actions 上の pnpm ワークスペース向けの高速な CI。変更されたパッケージのフィルタリング、ストアのキャッシュ、fetch-depth、マトリックスによるシャーディング、そしてそのままコピーして使える完全なワークフローを紹介します。