How to Shard Tests With a Matrix in GitHub Actions

A matrix over a shard index fans one test job into N parallel jobs, each running a distinct slice of the suite.

Define a shard dimension in strategy.matrix, pass the current index and the total to your runner, and let each job execute only its slice.

Steps

• Add a shard: [1, 2, 3, 4] dimension under strategy.matrix.
• Pass ${{ matrix.shard }} and the total shard count to the test command.
• Set fail-fast: false so one failing shard does not cancel the others.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --shard=${{ matrix.shard }}/4

Gotchas

• Keep the divisor (/4) in sync with the length of the matrix list.
• More shards cut wall-clock time but each pays fresh checkout and install cost.

Related guides