How to Batch Matrix Jobs in CI

A wide matrix multiplies per-job overhead. Batch combinations so you pay setup cost fewer times.

Every matrix leg has fixed overhead: provision, checkout, install. A huge matrix pays that tax N times. Batching trims N.

Prune with include/exclude

You rarely need every OS x version x flag combination. exclude removes redundant legs; include adds only the specific combos you care about.

Batch versions inside one job

Instead of one job per minor version, test a representative set in a single job loop to amortize setup overhead.

strategy:
  matrix:
    node: [18, 20, 22]
    exclude:
      - { node: 18, os: macos-latest }

Full matrix off the hot path

Run a slim matrix on PRs and the full matrix on main or nightly so day-to-day CI stays fast and cheap.

Key takeaways

• Every matrix leg pays fixed setup overhead.
• Prune with include/exclude; batch where you can.
• Reserve the full matrix for main/nightly.

Related guides