How to Refine a Cross-Platform Matrix With include and exclude

exclude removes combinations from the full cross-product; include adds extra cells or attaches keys to a specific combination.

A cross-platform matrix rarely needs every cell. Use exclude to prune combinations that do not apply, and include to add a one-off leg or extend a single cell.

Steps

• List base os and version dimensions.
• Add exclude: for pairs you do not support (for example old Node on Windows).
• Add include: to append a special leg or attach an extra flag.

Workflow

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

Gotchas

• exclude is applied first, then include adds cells back on top.
• An include entry whose keys match an existing cell extends that cell instead of creating a new job.

Related guides