GitHub Actions strategy.max-parallel appears ignored and all matrix jobs start at once

strategy.max-parallel caps how many legs of one matrix run concurrently, but it is bounded by runner availability and only applies within a single job’s matrix - not across jobs. With enough idle runners and a misplaced key, it can look like nothing throttles.

What this error means

Every matrix combination launches at the same time despite a max-parallel value meant to limit concurrency.

strategy:
  max-parallel: 2
  matrix:
    shard: [1, 2, 3, 4, 5, 6]
# all six shards start immediately

Common causes

max-parallel placed outside the strategy block

Only strategy.max-parallel is honored. Indented under matrix or at the job level it is ignored as an unknown key.

Throttle expected across jobs, not within one matrix

max-parallel limits legs of one matrix, not separate jobs. Concurrency across jobs needs the concurrency key or job needs chains.

How to fix it

Place max-parallel directly under strategy

1. Nest max-parallel as a sibling of matrix inside strategy.
2. Confirm it is a number, not quoted as a string.

jobs:
  test:
    runs-on: latchkey-small
    strategy:
      max-parallel: 2
      matrix:
        shard: [1, 2, 3, 4, 5, 6]

Throttle cross-job work with concurrency

1. For limiting unrelated jobs, use a concurrency group rather than max-parallel.
2. max-parallel only governs a single matrix expansion.

How to prevent it

• Keep strategy keys (matrix, max-parallel, fail-fast) at the same indentation level.
• Remember runner availability also caps real parallelism.

Related guides