Matrix Builds
A matrix build runs the same job across multiple variations — OS versions, language versions, environments. Catch “works on my machine” bugs in CI by testing every combo you support.
GitHub Actions matrix + include + exclude
EXAMPLE
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false # don't cancel siblings on one failure
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: [18, 20, 22]
# Add a one-off extra combo
include:
- os: ubuntu-latest
node: 21
flag: --experimental
# Drop a known-broken combo
exclude:
- os: windows-latest
node: 22
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm test ${{ matrix.flag || '' }}
summary:
# Required check that depends on the whole matrix passing
needs: test
runs-on: ubuntu-latest
steps:
- run: echo 'All matrix jobs green'
Why it matters
Set fail-fast: false when you want to see ALL failures in one run. The default cancels siblings on first failure — great for quick feedback, bad for debugging cross-platform issues.
Tip: Tweak the snippet with Try it Yourself », then sit the quiz at the bottom of the page.
Example
Example
strategy:
matrix:
node: [18, 20, 22]
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v4
with: { node-version: ${{ matrix.node }} }
Try it Yourself »
Exercise
Run a build across multiple Node versions.
strategy:
:
node: [18, 20, 22]
Six letters.
Discussion
Loading…