Matrix Strategies: Parallel Execution for Every Configuration

Modern software must run everywhere. Your application might need to support three different versions of Node.js across Linux, Windows, and macOS. Writing nine separate jobs manually is repetitive and prone to error. Matrix Strategies allow you to define a single job, provide a list of variables, and have GitHub Actions automatically spawn a "multiplied" grid of parallel jobs to test every possible combination.

The Need for Multi-Environment Testing
Defining a Simple Matrix
Advanced Matrix: Multi-Dimensional Grids
The power of 'include' and 'exclude'
Combining with Runs-On
Frequently Asked Questions
Key Takeaway

The Need for Multi-Environment Testing

In the past, developers would often test only on their local machine (e.g., macOS with Node 20). When they pushed to production (e.g., Linux with Node 18), hidden bugs would appear.

A Matrix Strategy forces your CI to be the ultimate safety net. It ensures that your code works across every configuration your users might actually be using, catching "environment-specific" bugs before they hit production.

Defining a Simple Matrix

You define a matrix inside the strategy key of a job.

yaml

When this workflow triggers, GitHub Actions will spawn three separate parallel jobs. One for Node 16, one for 18, and one for 20. If Node 16 fails but 18 and 20 pass, you instantly know your code isn't backwards compatible!

Advanced Matrix: Multi-Dimensional Grids

What if you need to test version and operating system?

yaml

This configuration will result in a 3x2 grid (6 total jobs). GitHub executes every possible permutation in parallel:

Ubuntu + Node 18
Ubuntu + Node 20
Windows + Node 18
Windows + Node 20
macOS + Node 18
macOS + Node 20

The power of 'include' and 'exclude'

Sometimes, a direct multiplication of variables creates jobs you don't want.

Exclude

Imagine you support Windows and Linux, but for some reason, Node 16 is deprecated on Windows. You can prevent that specific job from running:

yaml

This results in 3 jobs instead of 4.

Include

You can also inject a specific configuration that doesn't fit the multiplication.

yaml

Combining with Runs-On

To actually change the OS per job, you must reference the matrix variable in your runs-on property:

yaml

This is how multi-platform apps (like Electron or Flutter) build binaries for every platform simultaneously from a single YAML file.

Frequently Asked Questions

What is the maximum number of jobs in a matrix? GitHub allows up to 256 parallel jobs per workflow run in a matrix. If you accidentally define a matrix that creates 300 jobs (e.g., 20 versions x 15 OS), the workflow will throw a validation error.

What happens if one job in the matrix fails? By default, GitHub will immediately cancel all other running jobs in that matrix to save computing minutes (this is called fail-fast: true). You can disable this by setting fail-fast: false if you want to see exactly which versions failed even if one dies early.

Key Takeaway

Matrix strategies are the ultimate tool for cross-environment verification. By multiplying simple variable lists into a grid of parallel runners, you ensure that your code is robust across every version and operating system your ecosystem supports—without ever writing a single duplicate job definition.

Matrix Strategies: Parallel Execution for Every Configuration