Matrix Builds in GitHub Actions: Test Across Versions and Platforms

A matrix runs the same job with different combinations of values: several Node.js versions, operating systems or database versions, in parallel.

A basic matrix

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [20, 22, 24]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test

That's 3 x 3 = 9 jobs, each shown separately on the pull request.

include and exclude

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [20, 22]
    exclude:
      - os: windows-latest
        node: 20                  # skip this combination
    include:
      - os: ubuntu-latest
        node: 24
        experimental: true        # add an extra combination with an extra variable

Failure behaviour

strategy:
  fail-fast: false        # default true: one failure cancels the rest
  max-parallel: 4
  matrix: { node: [20, 22, 24] }
continue-on-error: ${{ matrix.experimental == true }}

Turn off fail-fast when you want to see every failing combination at once.

Splitting a slow test suite

strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx vitest run --shard=${{ matrix.shard }}/4

When to use a matrix

• Libraries: test every runtime version you claim to support.
• Apps: usually just the version you deploy, plus the next one before upgrading.
• Every combination uses runner minutes, so keep the matrix as small as gives you confidence.