Matrix Builds

Test combinations of OS, language version, dependency version, etc.

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
    python: ['3.10', '3.11', '3.12']

→ 3 × 3 = 9 jobs. Each gets variables ${{ matrix.os }}, ${{ matrix.python }}.

Useful for libraries: prove compatibility across the whole supported matrix.

Excludes:

matrix:
  os: [ubuntu-latest, macos-latest, windows-latest]
  python: ['3.10', '3.11', '3.12']
  exclude:
    - os: windows-latest
      python: '3.10'   # known-broken combo

Includes (for one-off variants):

include:
  - os: ubuntu-latest
    python: '3.13-dev'
    experimental: true

fail-fast: false keeps OTHER matrix jobs running even if one fails — useful for diagnosing which combos break.

Cost consideration: matrix multiplies CI minutes. A 50-job matrix on slow tests can burn through your free CI tier in a day.

Limit matrix size in PRs (run smaller matrix); full matrix on main pushes.