build matrixとは? バージョンとプラットフォームをまたぐテスト

著者 Kaveh Alemi·Latchkey

matrixは1つのjob定義を多数の並列なjobに変える - あなたが列挙した変数の組み合わせごとに1つ - jobをコピペせずにバージョンとプラットフォームをまたいでテストするために。

build matrixは、単一のjobを構成のグリッド全体に扇状に広げるコンパクトな方法だ。複数のOS、言語バージョン、依存関係セットで、あなたのコードが一度に動くことを証明する手段だ。

matrixの仕組み

値のリストを持つ変数を宣言する; CIシステムがデカルト積 - 組み合わせごとに1つのjob - を生成し、それらを並列に実行する。3-OS × 3-バージョンのmatrixは9つのjobに展開し、それぞれが同じstepの独立した実行だ。

2 × 3 = 6 jobs

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20, 22]

なぜ有用か

ユーザーより先に、バージョン固有・プラットフォーム固有のバグを捕まえる。
組み合わせを直列に実行する代わりに、カバレッジを並列化する。
広範な互換性テストを、数行のconfigで表現する。

コストの乗数

matrixは、課金対象の分を組み合わせの数だけ乗算する。短いjobの広いmatrixは、jobごとの分の切り上げでも罰せられる。グリッド全体を盲目的にテストするのではなく、シグナルをほとんど加えない組み合わせを削る(include/excludeを使い意味のあるペアだけをテストする)。

matrixとfail-fast

デフォルトでは、多くのシステムは1つのjobが失敗すると残りのmatrixをキャンセルする(fail-fast)。これは分を節約するが、失敗が1つの組み合わせに固有かどうかを隠す。すべての構成でpass/failのグリッド全体を見る必要があるときは、fail-fastを無効化する。

重要なポイント

matrixは1つのjobを、その変数のデカルト積に展開する。
速いクロスプラットフォームのカバレッジのために、組み合わせを並列に実行する。
コストは組み合わせの数に比例する - シグナルの低いものを刈り込む。
fail-fastは最初の失敗で兄弟をキャンセルする; グリッド全体を見るには無効化する。

よくある質問

What is What is a build Matrix? testing across versions and platforms?

A build matrix is a compact way to fan a single job out across a grid of configurations. It is how you prove your code works on multiple OSes, language versions, or dependency sets at once.

How a matrix works?

You declare variables with lists of values; the CI system generates the Cartesian product - one job per combination - and runs them in parallel. A 3-OS × 3-version matrix expands to nine jobs, each an isolated run of the same steps.

The cost multiplier?

A matrix multiplies billable minutes by the number of combinations. A wide matrix of short jobs is also punished by per-job minute rounding. Trim combinations that add little signal (use include/exclude to test only meaningful pairs) rather than blindly testing the full grid.

Matrix and fail-fast?

By default many systems cancel the rest of the matrix when one job fails (fail-fast). That saves minutes but hides whether the failure is specific to one combination. Disable fail-fast when you need to see the full pass/fail grid across all configurations.