GitHub Actions matrix "include" not applying (key rules) in CI

A matrix include entry extends an existing combination only when the keys it sets that also exist as vectors do not conflict. If none of its keys match a vector value, it creates a brand new job instead of adding a field to existing ones.

What this error means

An include entry you expected to add a value to certain legs instead spawns an extra standalone job, or does not attach to the legs you meant.

strategy:
  matrix:
    node: [18, 20]
    include:
      - color: green   # no matching vector key, so this creates a new job

Common causes

The include entry shares no vector key value

If an include object sets only keys that are not part of the base matrix (or values that match no existing combination), GitHub adds it as an additional job.

A conflicting value prevents the merge

When an include sets a vector key to a value that already exists but differs on another overlapping key, it will not overwrite the original combination.

How to fix it

Match an existing combination to extend it

1. Set the same vector key/value as the legs you want to extend.
2. Add the extra field alongside it in the same include entry.
3. Confirm the field appears on the intended legs, not a new job.

strategy:
  matrix:
    node: [18, 20]
    include:
      - node: 20
        experimental: true

Use include deliberately to add new jobs

If you actually want an extra combination, an include with new keys is correct; name the added job clearly so the intent is obvious.

How to prevent it

• Remember include extends when its vector keys match, else it adds a job.
• Set a matching vector value in include to attach fields to existing legs.
• Review the expanded matrix in the run summary to confirm behavior.

Related guides