Matrix Builds

A matrix turns one job definition into many. Declare a few axes — operating systems and language versions, say — and Actions runs the Cartesian product as separate, parallel jobs: three OSes times four versions is twelve jobs from a dozen lines of YAML. It is how you prove a library works everywhere it claims to, without copy-pasting a job per combination.

The controls around the grid are what make it practical: include and exclude trim or extend the set, fail-fast decides whether one failure cancels the rest, and max-parallel caps how many run at once.

The Matrix Grid

List multiple keys under strategy.matrix and Actions expands every combination into its own job. Reference the values with ${{ matrix.<key> }} — most often matrix.os in runs-on: so a single block targets every platform.

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

include and exclude

These two read as opposites and are constantly confused. exclude is the filter: it removes specific combinations from the generated grid, such as a runtime that does not build on an old OS. include does the reverse — it adds variables to combinations that already match, or appends entirely new combinations the product would not have produced.

A variable that only an include entry sets will be empty in every other job. If you read matrix.extra in a step, make sure every combination defines it, or guard the step with an if:.

fail-fast

The default is fail-fast: true, which cancels every in-progress matrix job the instant one fails. That is exactly wrong when you are trying to learn which versions broke, because the first failure hides the rest. Set fail-fast: false on test matrices so every combination reports its own result.

max-parallel

A wide matrix can spawn dozens of jobs at once, exhausting your concurrency limit or hammering an external API's rate limit. max-parallel caps how many matrix jobs run simultaneously, trading some wall-clock time for staying inside self-hosted capacity or third-party quotas.

Consuming Matrix Values

Beyond runs-on:, matrix values flow into any step expression. For data-driven sets, a prior job can emit a JSON array as an output and a later job can build its matrix from it with fromJSON() — so the combinations are computed at runtime rather than hardcoded.

Keeping the varying values in matrix.* and referencing them everywhere is what lets one job definition cover the whole grid instead of duplicating near-identical jobs.