What Is a Build Matrix? Testing Across Versions and Platforms
A matrix turns one job definition into many parallel jobs - one per combination of the variables you list - so you test across versions and platforms without copy-pasting jobs.
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.
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
node: [18, 20, 22]Why it is useful
- Catch version- and platform-specific bugs before users do.
- Parallelize coverage instead of running combinations serially.
- Express broad compatibility testing in a few lines of config.
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.
Key takeaways
- A matrix expands one job into the Cartesian product of its variables.
- It runs combinations in parallel for fast cross-platform coverage.
- Cost scales with the number of combinations - prune low-signal ones.
- fail-fast cancels siblings on first failure; disable it to see the full grid.