コンテンツへスキップ

GitHub Actions マトリックスビルドの正しい使い方

最終更新日

ビルドマトリックスは、OS、言語のバージョンなどの変数の組み合わせに対して同じジョブを実行します。複数のランタイムでライブラリをテストする標準的な方法ですが、気づかないうちに料金が3倍になることもあります。このガイドでは、構文、重要なオプション、コスト管理について説明します。

基本

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test

これにより 2 x 2 = 4 個のジョブが作成されます。GitHubではワークフロー実行ごとにマトリックスは256ジョブまでに制限されています。プッシュする前に、マトリックスエクスパンダーに記述を貼り付けると、すべての組み合わせとそのコストを確認できます。

include と exclude

exclude は組み合わせを削除し、include は組み合わせを追加または拡張します。

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [20, 22]
    exclude:
      - os: macos-latest
        node: 20
    include:
      - os: ubuntu-latest
        node: 24
        experimental: true

つまずきやすい点が2つあります。第一に、include のエントリは exclude の後に処理されます。第二に、キーが既存の組み合わせと一致する include エントリは、その組み合わせに追加の値を加えます(元の値は上書きされません)。どの組み合わせとも一致しないものは新しいジョブになります。上記の experimental のような一意のキーを追加し、${{ matrix.experimental }} で読み取ってください。

fail-fast と max-parallel

既定では fail-fast は true です。1つのジョブが失敗すると、GitHub は実行中の他のジョブをキャンセルします。これによって数分を節約できますが、失敗した組み合わせが1つしか分からないため情報が減ります。次のように使い分けてください。

  • ライブラリや互換性マトリックスで全体像を把握したい場合は fail-fast: false を使用します。
  • 1つのテストスイートをシャードに分割したマトリックスでは fail-fast: true(既定値)を使用します。どれか1つでも失敗すれば実行全体が無効になるためです。
strategy:
  fail-fast: false
  max-parallel: 4

max-parallel は、マトリックスから同時に実行されるジョブ数を制限します。ジョブがテストデータベースやAPIのレート制限などのリソースを共有する場合や、他のワークフローのために同時実行数を空けておきたい場合に便利です。既定ではプランが許す数だけ実行されます。

ジョブレベルで continue-on-error: ${{ matrix.experimental == true }} を指定すると、その組み合わせの失敗を許容できます。

コストを抑える

マトリックスの大きさは課金対象の分数を掛け合わせ、選択したOSは料金を掛け合わせます。GitHubのランナー料金では、Windowsは1分あたり$0.010、macOSは$0.062で、Linuxの$0.006と比べて高額です。無料枠の分数では、Windowsは2倍、macOSは10倍として消費されます。ジョブあたり10分の2つのマトリックスを比較してみてください。

マトリックスジョブ数実行あたりのコスト
3つのOS x 4つのNodeバージョン(全組み合わせ)124 x (10 x 0.006 + 10 x 0.010 + 10 x 0.062) = $3.12
Linux x 4バージョン、加えて最新版のWindowsとmacOS64 x 0.06 + 0.10 + 0.62 = $0.96

自分の構成で試すにはActionsコスト計算ツールを使用してください。実質的なカバレッジを損なわずにマトリックスを小さくする方法は次のとおりです。

  • すべてのセルではなく端を試す。サポートされている最も古いバージョンと最新バージョンで、互換性のバグのほとんどを検出できます。全セットは、すべてのプッシュではなく定期スケジュールでテストしてください。
  • 重いOSは一度だけ。WindowsとmacOSは、言語の1つのバージョンでのみ実行してください。
  • 2段階に分ける。PRでは小さなマトリックスを、main と夜間実行では完全なマトリックスを使用します。
  • 変更されたパスでスキップすることで、ドキュメントだけの変更では何も実行しないようにします。
  • 置き換えられた実行をキャンセルするには concurrency を使います。マトリックスが大きくなるほど重要になります。

動的マトリックス

マトリックスがリポジトリの状態に依存する場合は、最初のジョブで生成します。たとえばモノレポで変更されたパッケージのみを対象にする場合です。

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: set
        run: echo "matrix=$(node scripts/affected.mjs)" >> "$GITHUB_OUTPUT"
  build:
    needs: plan
    if: ${{ needs.plan.outputs.matrix != '[]' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ${{ fromJSON(needs.plan.outputs.matrix) }}
    steps:
      - run: npm run build -w ${{ matrix.package }}

生成されたマトリックスが空の場合、ジョブはエラーで失敗します。そのため if のガードを入れています。関連情報としてNxまたはTurborepoによるモノレポのCIも参照してください。

必須チェックとマトリックス

ブランチ保護はチェック名で照合されます。マトリックスのジョブには test (ubuntu-latest, 20) のような名前が付けられ、マトリックスを変更するとその名前も変わるため、必須チェックが「Expected」のまま止まってしまいます。マトリックスのジョブを必須にする必要がある場合は名前を明示的に指定するか、より良い方法として、マトリックス全体に依存する要約ジョブを1つ追加し、そのジョブだけを必須にしてください。

  all-tests:
    if: always()
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: test "${{ needs.test.result }}" = "success"

if: always() を使うと、マトリックスが失敗したときに要約ジョブが実行されて失敗します。これがないとジョブはスキップされ、スキップされたジョブが必須チェックを満たしてしまう場合があります。詳しくはGitHubのマージキューを参照してください。

マトリックスの値を安全に使う

マトリックスの値も式です。信頼できない入力(PRのラベルなど)から取得される場合は、スクリプトに直接埋め込まず、env を経由して渡してください。詳しくはGitHub Actionsのセキュリティ確保を参照してください。また、YAMLではバージョンを引用符で囲んでください。python: [3.9, 3.10] では 3.10 が数値の 3.1 として解釈されます。["3.9", "3.10"] と書いてください。

セルごとのキャッシュキー

セル同士が互いのキャッシュを上書きしないよう、キャッシュキーにマトリックスの値を含めてください。

key: npm-${{ matrix.os }}-node${{ matrix.node }}-${{ hashFiles('package-lock.json') }}

多くのセルが大きなキャッシュを書き込むと、リポジトリの10 GB制限に達することがあります。キャッシュガイドを参照してください。

よくある質問

マトリックスの最大サイズはどれくらいですか?

GitHubの利用上限に基づき、1回のワークフロー実行あたり256ジョブです。

マトリックスに、異なるランナーで実行されるジョブを含めることはできますか。

はい。runs-on: ${{ matrix.os }}を設定するか、各エントリにrunnerキーを含めてください。大型ランナーのラベルも使用できます。

マトリックスジョブに名前を付けるにはどうすればよいですか。

わかりやすいチェック名にするには、ジョブレベルでname: test (${{ matrix.os }}, node ${{ matrix.node }})を設定してください。

includeのエントリが新しいジョブを作成するのはなぜですか。

元のすべてのキーについて、既存の組み合わせと一致しないためです。タイプミスや、20と"20"のような型の違いを確認してください。

マトリックスで試す

マトリックスの実行に時間がかかる場合、ジョブ数と同じくらい、各セルの速度が重要になります。compiler.devの比較モードでは、1つのセルをより高速なマシンで実行するため、変更する前に、セルごとの実行時間とコストを確認できます。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す