GitHub Actions matrix include creates an unexpected combination
matrix include follows specific rules: if an include entry can be merged into an existing combination without overwriting a vector value, it augments it; otherwise it adds a new combination. Misunderstanding this produces surprise jobs.
What this error means
The matrix expands to more (or different) jobs than expected after adding include entries, with values applied to combinations you did not intend.
# Expected 2 jobs, got 3 because this include adds a new combination:
strategy:
matrix:
node: [18, 20]
include:
- node: 22
experimental: trueDiagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
include adds a new combination
An include with a vector value not already present creates an extra job.
include augments unexpectedly
An include that merges into existing combinations adds fields you did not anticipate.
How to fix it
Apply include rules deliberately
- Use include only to add fields to existing combinations or to add explicit new ones.
- List base vectors explicitly and verify the expanded job list.
- Use exclude to remove unwanted combinations rather than fighting include.
strategy:
matrix:
node: [18, 20]
include:
- node: 20
coverage: true # augments only the node:20 jobCatch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Review the expanded matrix in the Actions UI after editing include.
- Prefer exclude for trimming and explicit include entries for additions.