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: true

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

1. Use include only to add fields to existing combinations or to add explicit new ones.
2. List base vectors explicitly and verify the expanded job list.
3. 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 job

How to prevent it

• Review the expanded matrix in the Actions UI after editing include.
• Prefer exclude for trimming and explicit include entries for additions.

Related guides