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を使ってそれを読み取ります。
関連記事
- CIでDockerビルドが遅い?原因を特定して解決CIでDockerビルドが遅いですか?ビルドコンテキストのサイズ、.dockerignore、レイヤーの順序、キャッシュミス、BuildKitの設定を診断し、最も影響の大きい問題から修正しましょう。
- GitHub Actions マトリックスビルドの正しい使い方strategy.matrix で include、exclude、fail-fast、max-parallel を使い、ジョブ数と料金を適切に管理し、必須チェックを正しく設定する方法を説明します。
- リモートビルドキャッシュとは?リモートビルドキャッシュは、Nx、Turborepo、Gradle、Bazelなどのツールのタスク出力を保存し、CIやチームメンバーがすでに完了した作業をスキップできるようにします。仕組みはこちらです。
- CI分とは? GitHub Actionsの料金の仕組みCI分とは、パイプラインが使用する課金対象のコンピュート時間です。GitHub Actionsでの分の数え方、切り上げと乗数、そして使用量を減らす方法を説明します。