A GitHub Actions matrix runs one job once for every combination of the values you list, so three operating systems and two Python versions make six jobs. One matrix may generate at most 256 jobs, and each job is billed on its own, rounded up to a whole minute. Use include to add or extend combinations, exclude to remove them, and fail-fast and max-parallel to control how they run. Below: YAML we ran, and a tool that counts yours. If you find GitHub Actions slow, our guide has more fixes.
- A matrix runs a job once per combination of its values: three operating systems and two versions make six jobs.
- include extends a combination it fits or adds a job of its own, and it is processed after exclude.
- fail-fast defaults to true, and max-parallel has no default number.
- A matrix may generate 256 jobs. We ran 256, and GitHub started none of the legs of a 257-leg matrix.
- Each job is billed alone and rounded up to a whole minute, so a big matrix costs more than it looks.
- An empty fromJSON array fails the whole workflow unless an if guards the job that reads it.
We wrote each pattern below as a workflow, ran it on GitHub’s own runners on 17 November 2026, and checked what GitHub started against what the YAML says it should. The runs are public and linked as we go, and the workflows are in the ci-measurements repository. Where GitHub did something its documentation does not say, we say so.
Expand a matrix before you push it
Expanded in your browser. Your YAML is not uploaded.
It runs in your browser and sends nothing. Its rules are the ones in the sections below, and its output was checked against the job names GitHub printed for the include, exclude and operating-system examples on this page.
Operating system by version: the plain matrix
Every key under matrix that is a list is an axis, and GitHub runs the product of the axes. Three operating systems and two Python versions are six jobs.
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-24.04, ubuntu-22.04, windows-2025]
python: ["3.12", "3.13"]
steps:
- run: echo "${{ matrix.os }} with python ${{ matrix.python }}"
run 44063343664 started six jobs, named test (ubuntu-24.04, 3.12), test (ubuntu-22.04, 3.13) and so on: the job id, then the value of each axis in the order you wrote them. Quote the Python versions. YAML reads an unquoted 3.10 as the number 3.1, and we saw GitHub do exactly that, as the last section shows.
include: extend a combination or add a job
include does two different things, and which one you get depends on whether the object fits an existing combination. If it names only axis values that a combination has, its other keys are added to that combination. If it names an axis value no combination has, it becomes a job of its own. GitHub’s wording is that the original matrix values are never overwritten, but values added by an earlier include can be.
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-24.04, ubuntu-22.04]
node: [22, 24]
include:
# Fits the two node 22 combinations without overwriting anything: they gain npm.
- node: 22
npm: "10"
# Fits none of the four (node is 26), so it becomes a fifth job of its own.
- os: ubuntu-24.04
node: 26
experimental: true
steps:
- run: echo '${{ toJSON(matrix) }}'
run 44063352315 started five jobs. The first include fitted both node: 22 combinations, so each gained npm and kept its name. The second named node: 26, which is not an axis value, so it made a fifth job, and that job’s name carries every value it has: test (ubuntu-24.04, 26, true). A job made by an include is the only kind whose name lists the extra keys.
One thing the documentation does not say is how GitHub decides two values are the same. We tested it in run 44064539671. An include of the string "22" fitted the number 22. An include of ubuntu-24.04 fitted Ubuntu-24.04, so case is ignored. The string "true" did not fit the boolean true and made a new job. Treat that as what we saw on one day, not as a promise.
include on its own: a list of different jobs
A matrix with no axes, only include, is a list of jobs that share a definition but not their values. It is a tidy way to run lint, unit and end-to-end tests from one job block.
jobs:
check:
runs-on: ubuntu-24.04
strategy:
matrix:
include:
- { task: lint, command: "echo running lint" }
- { task: unit, command: "echo running unit tests" }
- { task: e2e, command: "echo running end-to-end tests" }
steps:
- run: ${{ matrix.command }}
run 44063360661 started three jobs, each named with every value it carries, such as check (lint, echo running lint).
exclude, and why include comes after it
exclude removes every combination of the product it matches, and a partial match is enough. Naming only os: windows-2025 removes every Windows job.
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-24.04, windows-2025]
python: ["3.12", "3.13"]
exclude:
- os: windows-2025
python: "3.12"
steps:
- run: echo "${{ matrix.os }} with python ${{ matrix.python }}"
run 44063369264 started three jobs: the four combinations minus the one the exclude names. Now the order of events. GitHub says all includes are processed after exclude, which lets you remove a whole group and add one back.
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-24.04, windows-2025]
python: ["3.12", "3.13"]
exclude:
# A partial match is enough: this removes both Windows jobs.
- os: windows-2025
include:
# Processed after exclude, so this puts one Windows job back.
- os: windows-2025
python: "3.13"
steps:
- run: echo "${{ matrix.os }} with python ${{ matrix.python }}"
run 44063378314 started three jobs: both Ubuntu jobs, and one Windows job, which the include added after the exclude had removed both. It is a good way to say “everything except Windows, plus Windows on the newest Python”.
A matrix built from the changed paths with fromJSON
When the legs depend on the change, build the list in a first job and hand it over as an output. The second job reads it with fromJSON. This one runs a leg for each directory under studies that the last commit touched.
jobs:
plan:
runs-on: ubuntu-24.04
outputs:
dirs: ${{ steps.dirs.outputs.dirs }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 2
- id: dirs
env:
OVERRIDE: ${{ inputs.paths }}
run: |
if [ -n "$OVERRIDE" ]; then
echo "dirs=$OVERRIDE" >> "$GITHUB_OUTPUT"
else
dirs=$(git diff --name-only HEAD~1 HEAD -- studies | cut -d/ -f2 | sort -u | jq -R . | jq -sc .)
echo "dirs=$dirs" >> "$GITHUB_OUTPUT"
fi
cat "$GITHUB_OUTPUT"
test:
needs: plan
# An empty array is not a matrix: without this guard the run fails when the matrix is evaluated.
if: needs.plan.outputs.dirs != '[]'
runs-on: ubuntu-24.04
strategy:
matrix:
dir: ${{ fromJSON(needs.plan.outputs.dirs) }}
steps:
- run: echo "would test studies/${{ matrix.dir }}"
With two paths, run 44063810621 started two test jobs. The if on the second job is not decoration. When the commit touched nothing under that path, the array was [] and the job was skipped (run 44063387374). Without the guard, the same empty array failed the whole workflow: GitHub reported “Error when evaluating ‘strategy’ for job ‘test’” and “Matrix vector ‘dir’ does not contain any values”, and only the first job ever ran (run 44064193197). An expander cannot count this kind of matrix, because its size is decided when the run starts.
fail-fast and max-parallel
fail-fast defaults to true: when any job in the matrix fails, GitHub cancels the others that are running or queued. max-parallel has no default number: GitHub runs as many as it has runners for. Both are strategy keys, beside matrix. The workflow below fails its second leg on purpose.
jobs:
test:
runs-on: ubuntu-24.04
strategy:
fail-fast: ${{ inputs.fail_fast }}
max-parallel: 2
matrix:
n: [1, 2, 3, 4, 5, 6]
steps:
- name: work
run: |
if [ "${{ matrix.n }}" = 2 ]; then sleep 5; echo "leg 2 fails"; exit 1; fi
sleep 25
With fail-fast: true, leg 2 failed after eight seconds and GitHub cancelled the other five, including legs that had not started (run 44063424740). With fail-fast: false, leg 2 failed and the other five finished (run 44063430086), and the start times show the cap at work: legs 1 and 2 first, then 3 and 4, then 5 and 6, never more than two at once. Set fail-fast: false when each leg is an independent answer, as it is for shards of one test suite.
Outputs from matrix jobs
A matrix job’s outputs are combined from all its legs. GitHub warns that it does not guarantee the order the legs run in, and that an empty output does not override another leg’s. So give each leg its own output name, written by the step and listed by name on the job. The output name cannot be built from matrix: our first attempt, with output_${{ matrix.version }} as the key, was refused before it ran.
jobs:
build:
runs-on: ubuntu-24.04
strategy:
matrix:
version: [1, 2, 3]
# The output names are fixed. Each leg writes the one named for it, and GitHub combines them.
outputs:
output_1: ${{ steps.gen.outputs.output_1 }}
output_2: ${{ steps.gen.outputs.output_2 }}
output_3: ${{ steps.gen.outputs.output_3 }}
shared: ${{ steps.gen.outputs.shared }}
steps:
- id: gen
run: |
echo "output_${{ matrix.version }}=built-${{ matrix.version }}" >> "$GITHUB_OUTPUT"
echo "shared=leg-${{ matrix.version }}" >> "$GITHUB_OUTPUT"
report:
needs: build
runs-on: ubuntu-24.04
steps:
- run: echo '${{ toJSON(needs.build.outputs) }}'
run 44063605573 printed output_1, output_2 and output_3 from the three legs. The shared output, which all three legs wrote, came back as leg-2. One leg won, and the workflow does not say which will. If you need every leg’s result, use one name per leg or upload an artifact per leg.
A matrix that calls a reusable workflow
A job that calls a reusable workflow can carry a matrix too, and pass each leg’s value in with with.
jobs:
call:
strategy:
matrix:
version: ["1.0", "2.0", "3.0"]
uses: ./.github/workflows/F1-09-callee.yml
with:
version: ${{ matrix.version }}
run 44063403258 started three jobs, named call (1.0) / test, call (2.0) / test and call (3.0) / test: the caller’s name, then the called job. The called workflow is in the repository.
How many jobs can a matrix make?
256 jobs, and GitHub’s limits table says Support cannot raise it. We tested the limit. A matrix of 256 legs ran all 256 (run 44064626921). A matrix of 257 started none of its legs: the job that builds the list ran, and then GitHub refused the matrix with “Strategy for job ‘leg’ produced 257 configurations which exceeds the maximum of 256 configurations” (run 44064615210).
GitHub’s pages say the limit is 256 jobs “per workflow run”. We also ran a workflow with two matrices of 130 legs each, 260 matrix jobs in one run, and all of them ran (run 44064638858). In practice the limit applies to each matrix, so a run can hold more than 256 jobs across several. The expander checks each matrix against 256.
A big matrix is also held back by concurrency. GitHub lists the total concurrent jobs for standard hosted runners as 20 on Free, 40 on Pro, 60 on Team and 500 on Enterprise. A 256-job matrix on a Free plan runs at most 20 legs at a time, and the rest queue. The limits post has the full table.
What a matrix costs
Every leg is a job, and GitHub rounds each job up to a whole minute. So the bill is the number of jobs, times the minutes each one takes rounded up, times the rate of the runner it ran on. A matrix of four Linux jobs and two Windows jobs at four minutes each, on standard 2-core runners, is 16 Linux minutes at $0.006 and 8 Windows minutes at $0.010: $0.176 a run. At 100 runs a month that is $17.60, before anything your plan includes.
Two things make a matrix cost more than it looks. A job of 61 seconds bills two minutes, so six legs of 61 seconds bill 12 minutes, not six. And a standard 2-core Windows leg draws down about 1.7 times what a 2-core Linux leg does. In a public repository standard runners are free; in a private one the plan’s included amount comes off the total first. The pricing post has the rates and the allowance by plan, and the workflow checker flags a matrix that is bigger than a pull request needs.
If the matrix exists to shard one test suite, the shard count is a cost decision of its own. We measured it in the test-splitting post.
Steps in a job can now run in parallel
People search for how to run steps in parallel inside one job. Until this year the workaround was to background a command with & in a shell, which GitHub says mixed the output together. Since 25 June 2026 you can run steps together with separate logs, using background, wait and parallel. Up to ten background steps run at once in a job, and none of them can be inside a composite action. We ran background, wait and parallel on a hosted runner.
jobs:
build:
runs-on: ubuntu-24.04
steps:
- name: sequential, 10 s then 10 s
run: |
date -u +%T; sleep 10; sleep 10; date -u +%T
- name: background a
id: a
background: true
run: |
sleep 10; echo "a=done" >> "$GITHUB_OUTPUT"
- name: background b
id: b
background: true
run: |
sleep 10; echo "b=done" >> "$GITHUB_OUTPUT"
- name: wait for a and b
wait: [a, b]
- name: read their outputs
run: echo "a=${{ steps.a.outputs.a }} b=${{ steps.b.outputs.b }}"
- parallel:
- name: p1
run: sleep 10
- name: p2
run: sleep 10
- name: after the group
run: date -u +%T
In run 44063610716, the two ten-second sleeps in a row took 22 seconds on the job’s clock. The two background steps, started together and waited for, finished 10 seconds after they began. The parallel group of two did the same. The background steps’ outputs were read after the wait, as GitHub says they must be. A matrix is the way to run the same job many times. Parallel steps are the way to overlap independent work inside one of them, and the run-less post covers when each is worth it.
Two traps in the YAML
The first is the number trap. run 44064181588 ran python: [3.9, 3.10, 3.11] unquoted and again quoted. The unquoted job was named unquoted (3.1), and there was no 3.10 at all. The quoted one ran quoted (3.10). Quote every version.
The second is the empty matrix, above: guard any matrix that comes from fromJSON with an if on the job that uses it.
We ran these on GitHub-hosted runners only. A matrix on a self-hosted runner is bound by the same 256-job limit, according to GitHub, and we did not run one. Build times measured on GitHub’s runner and on ours are on our faster GitHub Actions runners, measured page.
Sources
- Actions limits (docs.github.com)
- Workflow syntax for GitHub Actions (docs.github.com)
- Running variations of jobs in a workflow (docs.github.com)
- Actions runner pricing (docs.github.com)
- GitHub Actions billing (docs.github.com)
- Actions steps can now be run in parallel (GitHub changelog, 25 June 2026) (github.blog)
- The workflows and runs behind this post (ci-measurements, study F1) (github.com)
Frequently asked questions
How many jobs can a GitHub Actions matrix create?
At most 256 per matrix. A matrix of 256 ran in our test, and one of 257 started none of its legs and failed with an error. GitHub's table says Support cannot raise it, and it covers self-hosted runners too.
Does include run before or after exclude?
After. GitHub processes every include once exclude has run, so you can exclude a whole group, such as every Windows job, and use include to add one combination of it back.
Is fail-fast on by default in a matrix?
Yes. fail-fast defaults to true, so one failed job cancels the matrix's running and queued jobs. Set it to false when each leg is an independent result, such as shards of one test suite.
Do matrix jobs cost extra?
Each job is billed on its own, rounded up to a whole minute, at its runner's rate. Six jobs of 61 seconds bill 12 minutes. Standard runners in public repositories are free.
Can steps in a job run in parallel?
Yes, since 25 June 2026: background, wait and parallel run steps together, up to ten background steps in a job. On a hosted runner our two 10-second background steps finished in 10 seconds.