Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 44 ยท GitHub Actions Basics

Matrix Builds

Run one job across many operating systems and versions with a GitHub Actions matrix. Learn include, exclude, fail-fast, max-parallel and fromJSON.

Software rarely runs in only one place. A library may support three versions of a language on Linux, macOS and Windows. Copying a job nine times would be tedious and error-prone, so GitHub Actions offers the matrix strategy: you describe the axes (the things that vary) and GitHub creates one job for every combination.

This lesson explains how a matrix expands, how to add or remove individual combinations with include and exclude, how failure and parallelism are controlled, and how to build a matrix dynamically from JSON. The workflow YAML is read-only because it needs GitHub to run. The runnable examples are stand-ins that perform the same expansion in JavaScript so you can see exactly which jobs a matrix produces. They are a model of the rules, not GitHub's code.

Axes and combinations

A matrix lives under strategy. Every key under matrix is an axis, and every axis lists its values:

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

Two operating systems times two Node versions gives four jobs. Inside each job the matrix context holds that job's values, so matrix.os and matrix.node differ per job. Axes can also hold numbers, booleans and even objects. In the run list, GitHub names each job by its values, for example test (ubuntu-latest, 20), which is how you find a failing combination quickly.

flowchart TD
  M["matrix<br/>os x node"] --> A["ubuntu-latest, 20"]
  M --> B["ubuntu-latest, 22"]
  M --> C["windows-latest, 20"]
  M --> D["windows-latest, 22"]

One job definition fans out into one job per combination.

A single matrix can create at most 256 jobs, so very large grids need to be split or reduced.

Removing combinations with exclude

Maybe Windows does not need the oldest Node version. List the unwanted combination under exclude. An excluded entry matches every generated combination that contains all of its key-value pairs, so a partial entry can remove several jobs:

YAML
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [20, 22]
    exclude:
      - os: windows-latest
        node: 20
      - os: macos-latest

The first entry removes one job. The second names only os, so it removes both macOS jobs. The grid had six combinations, so three jobs remain.

exclude is applied to the combinations produced by the axes only. It cannot remove entries that include adds afterwards.

Adding combinations and extra values with include

include does two jobs that look similar but are different.

1. Add extra variables to existing combinations. If an entry only mentions values that match an existing combination (and adds new keys), those new keys are attached to the matching jobs:

YAML
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [20, 22]
    include:
      - os: windows-latest
        shell: pwsh

Both Windows jobs now have matrix.shell == 'pwsh'.

2. Add whole new jobs. If an entry does not match any existing combination, GitHub creates a new job from it:

YAML
    include:
      - os: ubuntu-latest
        node: 24
        experimental: true

There is no node: 24 in the axes, so this becomes a fifth job. The rule behind both cases: an include entry is added to a combination only if it would not overwrite one of the original axis values; if it cannot be added to any combination, it becomes a new one. Includes are processed in order after exclude.

A matrix may even be written only with include, which gives you a hand-written list of jobs, each with exactly the keys you need. That is often clearer than a grid when the combinations are irregular.

Controlling failure and parallelism

Two keys sit next to matrix under strategy:

YAML
strategy:
  fail-fast: false
  max-parallel: 2
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [20, 22]
  • fail-fast defaults to true: when one matrix job fails, GitHub cancels the jobs still running or queued. That saves minutes when you only want a quick red or green. Set it to false when you want the full picture, for example to learn that a bug affects only Windows.
  • max-parallel limits how many matrix jobs run at once. Use it to avoid overloading a shared test database or a rate-limited service. Without it, GitHub runs as many as the runners allow.

To let one experimental combination fail without failing the workflow, use continue-on-error on the job with an expression:

YAML
jobs:
  test:
    continue-on-error: ${{ matrix.experimental == true }}
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
        include:
          - node: 24
            experimental: true

For ordinary combinations matrix.experimental is missing, so it is null, the comparison is false, and the job behaves normally.

A matrix from JSON

Sometimes the list is not known until the workflow runs: which packages of a monorepo changed, which service folders exist. A first job can compute JSON and a second job can read it with fromJSON:

YAML
jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.make.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: make
        run: |
          echo 'matrix={"service":["api","web","worker"]}' >> "$GITHUB_OUTPUT"

  test:
    needs: plan
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}
    steps:
      - run: echo "Testing ${{ matrix.service }}"

The job output is a string, and fromJSON turns it into the object GitHub expects. This is the foundation of CI for monorepos. The output-passing mechanics were explained in Jobs, Steps and Dependencies.

Stand-in: expanding a matrix

The function below follows the rules above: it builds the cartesian product of the axes, removes combinations that contain every pair of an exclude entry, then applies each include entry either as extra keys or as a new job. Change the axes and see the job list update.

JS Matrix expansion with include and exclude

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The grid starts with six combinations. The two excludes remove three of them (one Windows job and both macOS jobs). The first include adds shell to the remaining Windows job, and the second does not match anything, so it becomes a new job. The result is four jobs.

Stand-in: fail-fast and max-parallel

The second model schedules jobs in batches of max-parallel and shows what fail-fast does when a job fails. Real scheduling is more fluid because jobs start as soon as a runner is free, but batches make the effect easy to see.

JS fail-fast versus fail-fast: false

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With fail-fast: true the failure in the second batch cancels the third. With false, every combination finishes and you see exactly what is broken.

Practical tips

  • Quote versions that look like numbers. In YAML 3.10 is read as 3.1, so write python: ["3.10", "3.12"]. The pitfall is explained in YAML for Pipeline Authors.
  • Put expensive combinations (macOS minutes cost more than Linux) in a separate job or under a condition, rather than multiplying the whole grid.
  • Make cache keys include the matrix values, or every job will fight over the same key. See Caching and Artifacts.
  • Matrix jobs that upload artifacts need unique artifact names, for example coverage-${{ matrix.os }}-${{ matrix.node }}.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A matrix has os: [ubuntu, windows] and node: [20, 22, 24]. With no include or exclude, how many jobs run?

    A matrix creates the cartesian product of its axes: 2 times 3 is 6 jobs.
  2. 2. What does an exclude entry with only os: macos-latest do?

    An exclude entry matches any combination that contains all of its pairs, so a partial entry removes several jobs at once.
  3. 3. An include entry has os: ubuntu-latest, node: 24, but 24 is not in the node axis. What happens?

    An include entry that would overwrite an original axis value cannot be merged into a combination, so it becomes a job of its own.
  4. 4. You need to know every failing combination, not just the first. Which setting helps?

    By default fail-fast cancels the remaining matrix jobs after one failure. Setting it to false lets all combinations finish.
  5. 5. How can a matrix be created from data computed earlier in the run?

    One job outputs JSON text, and the matrix is set to fromJSON(needs.<job>.outputs.<name>).

Summary

  • A matrix runs one job per combination of its axes and exposes the values through the matrix context; a matrix may create up to 256 jobs.
  • exclude removes every combination that contains all the pairs of an entry; include either adds keys to matching jobs or creates new jobs.
  • fail-fast (default true) cancels remaining jobs after a failure; max-parallel limits concurrency; continue-on-error can tolerate experimental entries.
  • fromJSON lets an earlier job generate the matrix at run time.
  • Quote version numbers, include matrix values in cache keys and artifact names.

Next: Caching and Artifacts