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

> build matrixは、同じjobを多数の組み合わせ - OS、言語バージョン、依存関係セット - で実行する。matrixの仕組みと、それがどうコストを乗算するかを学ぼう。

Source: https://latchkey.dev/ja/learn/ci-cd-concepts/what-is-a-build-matrix  
Updated: 2026-06-25

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を無効化する。

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt