GitHub ActionsでTurborepoモノレポを最速でCIする
最終更新
高速な Turborepo の CI は、次の 2 つから実現します。変更されたパッケージだけを実行すること、そしてリモートキャッシュからタスクの出力を再利用することです。Turborepo では前者に --filter、後者にリモートキャッシュを使います。このガイドでは、両方を GitHub Actions に組み込む方法と、それらが機能するかどうかを左右する git の設定を解説します。Nx との比較については、Nx と Turborepo の概要をご覧ください。
手順 1: 変更されたパッケージのみを実行する
turbo run build test lint --filter="...[origin/main]"
[origin/main] の部分は、origin/main 以降に変更があったパッケージを選択します。先頭の ... は、それらに依存するすべてのパッケージを追加します。CI ではこれが望ましい動作です。共有ライブラリの変更は、その利用側のテストも再実行する必要があるためです。... を付けない場合は、自身のファイルが変更されたパッケージだけが対象になります。
pnpm も同じセレクタ構文を使います。詳しくは pnpm のワークスペースをご覧ください。最近の Turborepo には、基準となるブランチを自動で選ぶ --affected フラグもあります。お使いのバージョンでの動作は、Turborepo のドキュメントでご確認ください。
Fetch-depth
origin/main に対するフィルタには、その ref と、マージベースを見つけるための十分な履歴が必要です。actions/checkout はデフォルトで 1 コミットしか取得しないため、次のいずれかを使用してください。
- uses: actions/checkout@v6
with:
fetch-depth: 0 # full history: safest
Turborepo の GitHub Actions ガイド(2026 年 10 月時点で確認)の例では fetch-depth: 2 が使われています。これは main の直前のコミットとの比較には十分ですが、長く続いている PR ブランチを origin/main と比較する場合には不十分です。PR では、完全な履歴を取得するか、fetch-depth: 0 と組み合わせた filter: tree:0 を使うのが安全な選択です。main への push では、直前のコミットと比較する方法が一般的です。
- run: turbo run build test --filter="...[HEAD^1]"
プルリクエストでは、基準となるブランチとの比較を動的に行えます。
- run: turbo run build test --filter="...[origin/${{ github.base_ref }}]"
if: github.event_name == 'pull_request'
手順 2: リモートキャッシュ
Turborepo のローカルキャッシュは node_modules/.cache/turbo に保存されますが、これは新しいランナーごとに消えてしまいます。リモートキャッシュは出力をハッシュ単位で保存するため、別のランナー、ブランチ、チームメンバーであっても、タスクを実行せずに同じ結果を得られます。
Turborepo のドキュメントでは、GitHub Actions で認証する方法を 2 通り説明しています。トークンを使う場合は、シークレットとして TURBO_TOKEN、変数として TURBO_TEAM を設定します。
jobs:
build:
runs-on: ubuntu-latest
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
ガイドには、vercel/setup-turborepo-remote-cache-action を使う OIDC 方式の説明もあります。この方式では id-token: write の権限が必要で、GitHub の短期間有効なトークンをキャッシュ用トークンと交換します。この設定は turbo を呼び出すどのステップよりも前に実行する必要があります。可能であれば OIDC を優先してください。長期間有効なシークレットが存在しないため、漏えいのリスクを減らせます。
キャッシュがヒットすると、出力にはハッシュ付きの cache hit, replaying logs が表示され、サマリー行には Cached: N cached, M total と報告されます。すべてがキャッシュから返された実行では FULL TURBO と表示されます。
ホスト型のキャッシュを使いたくない場合は、Turborepo のリモートキャッシュ API を実装したセルフホスト型のキャッシュサーバーを動かすか、.turbo を対象に actions/cache を使うこともできます。
- uses: actions/cache@v6
with:
path: .turbo
key: turbo-${{ runner.os }}-${{ github.sha }}
restore-keys: |
turbo-${{ runner.os }}-
これは GitHub Actions のキャッシュで説明しているローリングキャッシュのパターンです。Turborepo のキャッシュディレクトリを .turbo に向ければ機能します。ただし 10 GB の上限とブランチのスコープという制限があります。詳しくは キャッシュの制限をご覧ください。
手順 3: シャーディングと並列化
Turborepo は 1 台のマシン上でタスクを並列実行し、その上限は --concurrency(デフォルトは 10)で決まります。タスクを複数のマシンに分散する機能は備えていません。取れる選択肢は次のとおりです。
- コア数を増やす。 多くの場合、最も低コストな方法です。より大きなランナーでは
--concurrencyを引き上げられます。 - タスクごとのマトリクス。 lint、test、build をそれぞれ別のジョブとして実行し、各ジョブがリモートキャッシュを使うようにします。これにより、あるジョブで完了した作業を別のジョブが再利用できます。
- パッケージグループごとのマトリクス。 アプリごとに
--filterを使います。大規模なテストスイートの場合は テストのシャーディングと組み合わせてください。
strategy:
fail-fast: false
matrix:
task: [lint, test, build]
steps:
- run: turbo run ${{ matrix.task }} --filter="...[origin/main]"
マトリクスの各ジョブでは、チェックアウトとインストールの時間が毎回かかるため、依存関係のキャッシュを適切に設定してください。詳しくは pnpm のキャッシュと npm のキャッシュをご覧ください。
完全なワークフロー
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
ci:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
timeout-minutes: 20
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- name: Run changed packages
run: pnpm turbo run lint test build --filter="...[origin/${{ github.base_ref || 'main' }}]"
push の場合、github.base_ref は空になるため、式は main にフォールバックします。main 自体で実行すると main と main を比較することになり、何も選択されません。そのため push では --filter="...[HEAD^1]" を使うか、すべてを実行してキャッシュによる再利用に任せてください。
compiler.dev では、runs-on の行を変更すると、依存関係のキャッシュが準備された 8 vCPU のマシンを分あたり $0.008 で利用できます。元に戻すには、その行を書き換えるだけです。Turborepo、Next.js、tRPC、MySQL を使ったプロジェクトで実測したところ、CI の時間は GitHub ホストのランナーでの 3m29s から 1m53s に短縮されました(ベンチマークをご覧ください)。
フィルタリングを無効にしてしまう間違い
- 浅いクローン。 マージベースが見つからないと、Turborepo は多くのパッケージを変更済みとして扱います。
- キャッシュキーの入力が広すぎる。 タスクにハッシュとして取り込まれるパッケージ外のファイル(
turbo.jsonのグローバル依存関係)は、変更されるとすべてを無効化します。 - 環境変数が宣言されていない。 タスクが
envやglobalEnvにない環境変数を読み込むと、キャッシュエントリが誤って共有されたり、誤って見逃されたりする可能性があります。 - ジョブ間で
TURBO_TEAMが異なる。 この場合、ジョブごとに別のキャッシュを使ってしまいます。 - 信頼されていない PR がキャッシュに書き込む。 書き込み権限は信頼されたブランチに限定してください。
よくある質問
turbo --filter における ...[origin/main] はどういう意味ですか?
origin/main 以降に変更されたパッケージに加え、先頭の ... により、それらに依存するパッケージも対象になります。
リモートキャッシュには Vercel が必要ですか?
ドキュメントに記載のホスト型オプションは Vercel のものです。互換性のあるセルフホスト型のキャッシュサーバーを動かすこともできます。
なぜ main では CI がすべてを再ビルドするのですか?
push の場合は PR の基準となるブランチがありません。直前のコミットや直近の成功したコミットと比較するか、リモートキャッシュによる再利用に任せてください。
Turborepo はタスクを複数のマシンに分散しますか?
それ自体では分散しません。上記のとおり、マトリクスを使うか、より大きなランナーを利用してください。
関連記事
- 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、完全なワークフローを紹介します。
- GitHub ActionsでpnpmワークスペースのCIを最速化するGitHub Actions 上の pnpm ワークスペース向けの高速な CI。変更されたパッケージのフィルタリング、ストアのキャッシュ、fetch-depth、マトリックスによるシャーディング、そしてそのままコピーして使える完全なワークフローを紹介します。
- NxまたはTurborepoによるモノレポのCI: 影響を受けるビルドGitHub Actions でモノレポの変更部分だけを実行します。Nx の affected、Turborepo のフィルタ、リモートキャッシュ、パスフィルタ、そして重要なチェックアウトの設定を解説します。