matrix
strategy:
Fans a job out across a matrix of variable combinations. Each combination becomes an independent job whose values are exposed via the `matrix` context.
strategy:
matrix:
<key>: [v1, v2]
include: [...]
exclude: [...]
fail-fast: true|false
max-parallel: <n>Common values / subkeys
| Value / Subkey | Purpose |
|---|---|
| matrix.<key> | List of values to enumerate; multiple keys are combined cartesian-product |
| matrix.include | Add extra combinations or attach extra fields to matching combos |
| matrix.exclude | Remove specific combinations |
| fail-fast | Cancel remaining legs when one fails (default true) |
| max-parallel | Limit concurrent legs |
| ${{ matrix.<key> }} | Read the current leg's value inside the job |
Examples
strategy:
matrix:
node: [18, 20, 22]
os: [ubuntu-latest, windows-latest]Cartesian product: 6 jobs
strategy:
matrix:
node: [18, 20]
include:
- node: 22
experimental: true`include` adds a new leg; matching existing combos merges extra fields
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]Keep other legs running when one fails
strategy:
matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}Dynamic matrix built from an upstream job output
Gotcha
`include` adds a NEW combination unless every key it names already exists in a generated combo — then it merges into that combo; `exclude` is applied after `include`. Matrix is capped at 256 jobs per workflow run.
Related keywords
jobs:
Top-level map of jobs that run in parallel by default. Each job has an ID (used by `needs:` and outputs) and either a `steps:` list or a `uses:` reference to a reusable workflow.
runs-on:
Selects the runner (or runner group) that will execute the job. Accepts a single label, an array to match multiple labels (self-hosted), or an object form for larger runners and runner groups.
contains / startsWith / format / join / fromJSON
Built-in functions available inside `${{ }}` expressions. GitHub Actions does not allow user-defined functions — only the documented list is valid.