How to Limit Concurrent Matrix Jobs With max-parallel in GitHub Actions

max-parallel caps how many matrix legs run simultaneously, queuing the rest instead of launching them all at once.

Set strategy.max-parallel to the number of legs you want running concurrently. GitHub starts that many and releases the next as each finishes.

Steps

• Add max-parallel: under strategy.
• Pick a number below your total legs to throttle them.
• Use it when legs share a rate-limited external resource.

Workflow

jobs:
  test:
    strategy:
      max-parallel: 2
      matrix:
        shard: [1, 2, 3, 4, 5, 6]
    runs-on: ubuntu-latest
    steps:
      - run: npm ci && npm test -- --shard=${{ matrix.shard }}/6

Gotchas

• max-parallel throttles concurrency but does not reduce the total job count or minutes.
• It is a per-matrix limit; concurrency across workflows needs a concurrency: group.

Related guides