How to Skip a Matrix Leg Conditionally in GitHub Actions

A step-level if that reads the matrix context lets specific legs no-op without removing them from the matrix.

Guard the real work with if: referencing matrix values. The leg still starts (and reports success) but the expensive steps are skipped.

Steps

• Keep the full matrix so job status stays consistent.
• Add if: on the heavy step referencing the matrix key.
• Prefer exclude when you want the leg to disappear entirely.

Workflow

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        suite: [unit, e2e]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - name: Run e2e only on Linux
        if: matrix.suite != 'e2e' || matrix.os == 'ubuntu-latest'
        run: npm run test:${{ matrix.suite }}

Gotchas

• A skipped step still counts the leg as successful, which can hide missing coverage.
• For a truly absent combination, use exclude so it never spins up a runner.

Related guides