What Is a Matrix Strategy?
A matrix strategy runs one job definition across many input combinations at once - every OS times every language version, in parallel.
You often need to test the same code under many conditions: three Node versions, two operating systems, both architectures. Writing six near-identical jobs is tedious. A matrix declares the dimensions once and CI expands them into parallel jobs for you.
How a matrix expands
You list dimensions and their values; CI generates the cross-product. A matrix of os: [ubuntu, windows] and node: [18, 20, 22] expands to six jobs - one per combination - that run in parallel.
A small example
A strategy.matrix with node: [18, 20, 22] runs your test suite three times, once per version, each on its own runner. The job name shows the value (test (20)) so a failure points straight at the version that broke.
Includes and excludes
You can add one-off combinations with include or drop specific cells with exclude, so you cover the combinations that matter without testing every cell of a large grid.
Fail-fast behavior
By default many matrices are fail-fast: one failing cell cancels the rest. Turning fail-fast off lets every cell finish, so you see whether a failure is one flaky combination or a broad regression across all of them.
Watch the combinatorial blowup
Dimensions multiply. Four values across three dimensions is 64 jobs - fast feedback but real cost. Keep matrices to the combinations that genuinely differ in behavior.
Key takeaways
- A matrix runs one job across the cross-product of input dimensions.
- include and exclude let you tune which combinations run.
- Dimensions multiply fast - keep matrices to what truly matters.