Test Across Multiple Versions with Matrix Builds
Matrix builds catch compatibility issues early by testing every version and OS combo in parallel.
What
Matrix builds let you test your code against multiple versions of languages, operating systems, or dependencies in parallel. In GitHub Actions, the strategy.matrix key generates a job for each combination. Instead of writing separate jobs for Node 18, 20, and 22, a single matrix definition handles all of them automatically.
Why It Matters
Your users run different versions of runtimes and operating systems. A feature that works on Node 22 might break on Node 18 due to missing APIs. Matrix builds catch these compatibility issues before they reach production, without you manually maintaining separate CI jobs for each version.
Example
# .github/workflows/test.yml
name: Test Matrix
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
node-version: [18, 20, 22]
os: [ubuntu-latest, macos-latest]
fail-fast: false # Don't cancel other jobs if one fails
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm testCommon Mistake
Creating too many matrix combinations that eat through CI minutes. A matrix of 3 Node versions x 3 OS types x 3 database versions = 27 parallel jobs. Use exclude or include to limit combinations to only the ones that matter.
Quick Fix
Add fail-fast: false so all matrix jobs complete even if one fails, and use exclude to remove unnecessary combinations like Node 18 on macos-latest if you only deploy to Linux.
Key Takeaways
- 1strategy.matrix generates a job for each combination automatically
- 2Test multiple Node versions: [18, 20, 22] in parallel
- 3Test across OS types: ubuntu-latest, macos-latest
- 4Use fail-fast: false to let all combinations finish
- 5Use exclude/include to control which combos actually run
Was this tip helpful?
Help us improve the DevOpsPath daily collection