Matrix Builds
Test across multiple Node versions, OS, and configurations in parallel with one job definition
Skills taught: cicd.matrix, cicd.matrix-strategy, cicd.include-exclude, cicd.fail-fast
What is a matrix build?
A matrix build runs the same job multiple times with different values — simultaneously, in parallel. Instead of writing three separate jobs to test on Node 18, 20, and 22, you define one job with a matrix of three values and GitHub creates three parallel jobs automatically.
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22]
# fail-fast: false means all matrix jobs complete even if one fails
# Good for finding ALL compatibility issues, not just the first
fail-fast: false
name: Test on Node ${{ matrix.node-version }}
steps:
- uses: actions/checkout@v4
- name: Setup Node ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- run: npm ci
- run: npm test
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node: [18, 20]
# Creates 3 OS × 2 Node = 6 parallel jobs:
# ubuntu-18, ubuntu-20, windows-18, windows-20, mac-18, mac-20
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm test
jobs:
test:
strategy:
matrix:
node: [18, 20, 22]
os: [ubuntu-latest, windows-latest]
# include: ADD extra jobs with additional properties
include:
# Run Node 20 on macOS too (not in the base matrix)
- node: 20
os: macos-latest
# Add an extra env var only for Node 22 jobs
- node: 22
experimental: true
# exclude: REMOVE specific combinations
exclude:
# Skip Node 18 on Windows
- node: 18
os: windows-latest
runs-on: ${{ matrix.os }}
# Mark experimental jobs so failure doesn't fail the whole workflow
continue-on-error: ${{ matrix.experimental == true }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '${{ matrix.node }}' }
- run: npm ci && npm test
Tip: Keep matrices focused. A 3×3×3 matrix = 27 parallel jobs. Each uses CI minutes and contributes to runner queue wait time. For most projects, testing on the LTS Node version on Ubuntu is sufficient for PRs, with a broader matrix on release branches. Don't matrix for the sake of it.
Frequently Asked Questions
Can I use a matrix for deployment targets?
Yes — matrix: environment: [staging, eu-west, us-east] lets you deploy to multiple regions in parallel. Combine with environment protection rules to require approval for each. This pattern is common for multi-region global deployments.