コンテンツへスキップ

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)で決まります。タスクを複数のマシンに分散する機能は備えていません。取れる選択肢は次のとおりです。

  1. コア数を増やす。 多くの場合、最も低コストな方法です。より大きなランナーでは --concurrency を引き上げられます。
  2. タスクごとのマトリクス。 lint、test、build をそれぞれ別のジョブとして実行し、各ジョブがリモートキャッシュを使うようにします。これにより、あるジョブで完了した作業を別のジョブが再利用できます。
  3. パッケージグループごとのマトリクス。 アプリごとに --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 に短縮されました(ベンチマークをご覧ください)。

フィルタリングを無効にしてしまう間違い

  1. 浅いクローン。 マージベースが見つからないと、Turborepo は多くのパッケージを変更済みとして扱います。
  2. キャッシュキーの入力が広すぎる。 タスクにハッシュとして取り込まれるパッケージ外のファイル(turbo.json のグローバル依存関係)は、変更されるとすべてを無効化します。
  3. 環境変数が宣言されていない。 タスクが env や globalEnv にない環境変数を読み込むと、キャッシュエントリが誤って共有されたり、誤って見逃されたりする可能性があります。
  4. ジョブ間で TURBO_TEAM が異なる。 この場合、ジョブごとに別のキャッシュを使ってしまいます。
  5. 信頼されていない PR がキャッシュに書き込む。 書き込み権限は信頼されたブランチに限定してください。

よくある質問

turbo --filter における ...[origin/main] はどういう意味ですか?

origin/main 以降に変更されたパッケージに加え、先頭の ... により、それらに依存するパッケージも対象になります。

リモートキャッシュには Vercel が必要ですか?

ドキュメントに記載のホスト型オプションは Vercel のものです。互換性のあるセルフホスト型のキャッシュサーバーを動かすこともできます。

なぜ main では CI がすべてを再ビルドするのですか?

push の場合は PR の基準となるブランチがありません。直前のコミットや直近の成功したコミットと比較するか、リモートキャッシュによる再利用に任せてください。

Turborepo はタスクを複数のマシンに分散しますか?

それ自体では分散しません。上記のとおり、マトリクスを使うか、より大きなランナーを利用してください。

このモノレポのビルドをcompiler.devで実行 カード登録不要 · 200 無料分

無料で試す