コンテンツへスキップ

GitHub Actionsのマトリックスビルドとは

最終更新

マトリックスビルドは、1つのジョブ定義を、指定した変数の組み合わせごとの多数の並列ジョブに展開するGitHub Actionsの戦略です。たとえばオペレーティングシステムや言語のバージョンなどが対象になります。

仕組み

ジョブにstrategy.matrixを追加し、1つ以上のキーに値のリストを指定します。GitHubは組み合わせごとに1つのジョブを作成し、それぞれを独自のランナーで実行します。ジョブ内では、現在の値を${{ matrix.<key> }}で読み取れます。

3つの値を持つリストが2つあると、9つのジョブが生成されます。ジョブ数はすぐに増え、各ジョブはCI分を消費するため、幅の広いマトリックスはコストがかさむ場合があります。

例

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

便利なオプション

  • includeは、既存の組み合わせに追加の組み合わせや変数を加えます。
  • excludeは、不要な組み合わせを取り除きます。
  • fail-fast(既定値はtrue)は、いずれかのジョブが失敗した場合に残りのジョブをキャンセルします。全体の結果を確認したい場合はfalseに設定してください。
  • max-parallelは、同時に実行するマトリックスジョブの数を制限します。

マトリックス展開ツールで、展開結果をプレビューできます。詳しくはGitHub Actionsのマトリックスビルドのガイドをご覧ください。

よくある間違い

  • マトリックスが不要な場合。1つのプラットフォームでしか出荷しないアプリに対して3つのNodeバージョンをテストすると、時間が無駄になります。
  • デバッグ中もfail-fastを有効にしたままにする。不安定な1つのジョブがほかのジョブをキャンセルし、実際の失敗を隠してしまいます。
  • 速度向上のためのマトリックス。同一のジョブを並べたマトリックスでは、作業は分割されません。1つのテストスイートを複数のマシンに分散するには、テストシャーディングを使用してください。
  • 必須チェックが多すぎる。マトリックスの各レグは個別のチェック名になるため、ブランチprotectionの管理が複雑になります。
  • 上限の超過。1つのマトリックスは、ワークフロー実行あたり256ジョブが上限です。

よくある質問

マトリックスとテストシャーディングの違いは何ですか?

マトリックスは、ジョブ全体を異なる構成で実行します。シャーディングは、1つの構成内のテストをスライスに分割します。シャードのインデックスをマトリックス変数として使うことで、両者を組み合わせることもできます。

マトリックスのジョブは並列に実行されますか?

はい。ランナーの容量と同時実行数の制限の範囲内で並列に実行されます。抑制したい場合はmax-parallelを使用してください。

マトリックスを動的に生成できますか?

はい。あるジョブがJSONを出力し、後続のジョブがstrategy.matrix内でfromJSONを使ってそれを読み取ります。