Matrix Strategy Deep Dive

Matrix is more than a Cartesian product

The matrix expands every combination of the listed dimensions, but you usually want to shape the result, not run the full product. Three controls:

include: — append specific cells (with extra fields) on top of the Cartesian product.
exclude: — remove specific cells from the Cartesian product.
fail-fast: false — keep all cells running even if one fails (default is true).

Patterns you'll reach for

Add an experimental cell with a flag. Run Python 3.13 in addition to 3.10–3.12 with continue-on-error: true so it doesn't block PRs.
Skip combinations that don't apply. Postgres 16 + Python 3.10 may not be supported by your driver — exclude it.
Inject extra config per cell. Different DB connection strings, different timeouts, different test markers.
Dynamic matrix. Generate the matrix from a jobs.outputs in a previous job (covered in the reuse track).

fail-fast tradeoff

fail-fast: true (default) cancels remaining cells the moment any cell fails. Saves minutes; loses information. fail-fast: false runs everything to completion. Pick true on PRs (fast feedback), false on main (full visibility).

Code

Include / exclude / continue-on-error·yaml

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        python: ['3.10', '3.11', '3.12']
        exclude:
          # Skip macOS x 3.10 (slow + low value)
          - os: macos-latest
            python: '3.10'
        include:
          # Try the bleeding-edge cell, but don't fail the matrix on it
          - os: ubuntu-latest
            python: '3.13-dev'
            experimental: true
    continue-on-error: ${{ matrix.experimental == true }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '${{ matrix.python }}' }
      - run: pip install -e . && pytest -q

Matrix Strategy Deep Dive

Matrix is more than a Cartesian product

Patterns you'll reach for

fail-fast tradeoff

Code

External links

Exercise

Progress

Comments 0