GitHub Actions matrix expander

How GitHub expands a matrix

GitHub turns strategy.matrix into jobs in three steps:

1. Product. Every key that holds a list is combined with every other: os: [a, b] × node: [20, 22] gives four jobs.
2. Exclude. Each exclude entry removes every combination that matches all of its keys. An entry may list only some keys: - os: windows-latest removes every Windows job.
3. Include. Each include entry is merged into every original combination whose original values it doesn’t contradict. If it contradicts all of them, it becomes a new job of its own.

Include is the step people get wrong. It never overwrites an original value, it can overwrite values added by an earlier include, and the new jobs it creates do not pick up keys from other include entries.

Example

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [20, 22]
    exclude:
      - os: windows-latest
        node: 20
    include:
      - node: 22
        lts: true
      - os: macos-latest
        node: 22

This produces four jobs:

The first include adds lts: true to both existing node: 22 jobs. The second contradicts every original os value, so it becomes a new job. That new job does not get lts: true, because includes never apply to jobs created by other includes.

Tips for large matrices

• Exclude broadly. One exclude entry with a single key can remove a whole row of the matrix.
• Use include for one-off jobs. A coverage run or a nightly toolchain is cleaner as an include than as another matrix dimension.
• Cap concurrency. max-parallel stops a 50-job matrix from using every runner in your organisation.
• Turn off fail-fast for compatibility matrices. You usually want to see every failing platform, not just the first.
• Keep names readable. Set name: test (${{ matrix.os }}, node ${{ matrix.node }}) on the job so the checks list stays scannable.