Test Sharding in GitHub Actions: Speed Up CI by 10x

Test Sharding in GitHub Actions: Speed Up CI by 10x

A 20-minute CI pipeline is a 20-minute feedback loop. Developers stop running tests locally, pull requests pile up waiting for green builds, and the "just push and see" habit takes root. Test sharding — splitting your test suite across multiple parallel CI runners — is one of the highest-leverage changes you can make to a slow pipeline.

This guide covers exactly how to implement sharding in GitHub Actions using the matrix strategy, how Jest and Vitest handle sharding natively, how to split by duration instead of file count, and how to merge coverage reports from multiple shards back into one.

What Test Sharding Is (and Isn't)

Sharding is different from running tests in parallel within a single machine. With parallelism, you have one CI job with multiple worker threads or processes. With sharding, you have multiple CI jobs, each running a subset of the test suite, all executing simultaneously.

The distinction matters because GitHub Actions charges per runner-minute, and each job in a matrix runs on a separate runner. Sharding trades runner cost for wall-clock time: 10 shards running for 2 minutes each costs the same as 1 shard running for 20 minutes, but your pipeline finishes in 2 minutes instead of 20.

GitHub Actions Matrix Strategy for Sharding

The foundation is the matrix strategy, which lets you parameterize a job over a set of values:

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false  # Don't cancel other shards if one fails
      matrix:
        shard: [1, 2, 3, 4, 5]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Run tests (shard ${{ matrix.shard }} of 5)
        run: npx jest --shard=${{ matrix.shard }}/5

This creates 5 parallel jobs. Each job receives a different shard value from the matrix. GitHub Actions schedules them concurrently (up to the concurrency limit on your plan).

The fail-fast: false setting is important: without it, if shard 2 fails, GitHub Actions cancels shards 3, 4, and 5 before they finish, so you don't see the full failure picture.

Jest Native Sharding with --shard

Jest has built-in sharding support since version 28. The --shard flag takes the format <index>/<total>:

# Run shard 1 of 5
jest --shard=1/5

# Run shard 3 of 5
jest --shard=3/5

Jest distributes test files across shards deterministically based on file path sorting. Shard 1 always gets the same files for the same test suite, which makes the split reproducible and cacheable.

# Full example with coverage
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci

      - name: Run Jest shard ${{ matrix.shard }}/5
        run: |
          npx jest \
            --shard=${{ matrix.shard }}/5 \
            --coverage \
            --coverageDirectory=coverage/shard-${{ matrix.shard }}

      - name: Upload coverage artifact
        uses: actions/upload-artifact@v4
        with:
          name: coverage-shard-${{ matrix.shard }}
          path: coverage/shard-${{ matrix.shard }}
          retention-days: 1

Vitest Sharding

Vitest added sharding support in v0.32. The API mirrors Jest's:

vitest run --shard=1/5
vitest run --shard=2/5
# vitest.config.ts changes nothing — sharding is a CLI flag
- name: Run Vitest shard ${{ matrix.shard }}/5
  run: npx vitest run --shard=${{ matrix.shard }}/5 --coverage

One advantage of Vitest sharding: because Vitest uses Vite's module graph, it can potentially make smarter decisions about how to group related test files in the future. For now, the split is also alphabetical by file path.

Splitting by File Count vs. by Test Duration

The default alphabetical split has a significant flaw: your test files are not uniformly sized. If your E2E tests live under tests/e2e/ and all file paths starting with e end up in shard 2, that shard takes 5x longer than the others.

Measuring Test Duration

First, get a baseline of per-file durations:

# Jest with JSON reporter
jest --json --outputFile=test-results.json

# Extract durations with jq
jq '[.testResults[] | {file: .testFilePath, duration: .perfStats.runtime}] | sort_by(-.duration)' test-results.json

Static Duration-Based Splitting

With duration data, you can create a custom shard list:

// scripts/generate-shards.js
const results = require('./test-results.json');

const files = results.testResults.map(r => ({
  path: r.testFilePath,
  duration: r.perfStats.runtime,
})).sort((a, b) => b.duration - a.duration);

const NUM_SHARDS = 5;
const shards = Array.from({ length: NUM_SHARDS }, () => ({ files: [], duration: 0 }));

// Greedy bin-packing: assign each file to the shard with current minimum total duration
for (const file of files) {
  const minShard = shards.reduce((min, shard, i) =>
    shard.duration < shards[min].duration ? i : min, 0);
  shards[minShard].files.push(file.path);
  shards[minShard].duration += file.duration;
}

// Output as JSON for GitHub Actions
console.log(JSON.stringify(shards.map(s => s.files)));

Then use this in your workflow:

jobs:
  generate-shards:
    runs-on: ubuntu-latest
    outputs:
      shards: ${{ steps.generate.outputs.shards }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - name: Generate shards
        id: generate
        run: |
          SHARDS=$(node scripts/generate-shards.js)
          echo "shards=$SHARDS" >> $GITHUB_OUTPUT

  test:
    needs: generate-shards
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard-index: [0, 1, 2, 3, 4]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          cache: 'npm'
      - run: npm ci

      - name: Run tests for shard ${{ matrix.shard-index }}
        run: |
          SHARD_FILES=$(echo '${{ needs.generate-shards.outputs.shards }}' | \
            jq -r '.[${{ matrix.shard-index }}] | join(" ")')
          npx jest $SHARD_FILES

Merging Coverage Reports

When each shard produces its own coverage report, you need to merge them before sending to a coverage service like Codecov or generating a unified report.

  merge-coverage:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          cache: 'npm'
      - run: npm ci

      - name: Download all coverage artifacts
        uses: actions/download-artifact@v4
        with:
          pattern: coverage-shard-*
          merge-multiple: false
          path: coverage-shards

      - name: Merge coverage reports
        run: |
          npx nyc merge coverage-shards/coverage-shard-*/coverage-final.json \
            merged-coverage.json
          npx nyc report \
            --reporter=lcov \
            --reporter=text-summary \
            --temp-dir=. \
            --report-dir=coverage

      - name: Upload to Codecov
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info
          fail_ci_if_error: true

For Vitest, coverage merging uses @vitest/coverage-v8 or @vitest/coverage-istanbul:

# Merge Vitest coverage
npx vitest-coverage-report merge \
  coverage-shards/coverage-shard-*/coverage-final.json \
  --output coverage/coverage-final.json

Real Before/After Timing

Here are measured results from a real Next.js application with 847 test files:

Before sharding (single runner):

  • Total CI time: 18 minutes 42 seconds
  • Jest workers: 4 (default for 4-vCPU runner)
  • Monthly runner cost (100 PRs/month): ~31 runner-hours

After sharding (5 shards, alphabetical split):

  • Total CI time: 5 minutes 11 seconds
  • Each shard runs: 169-170 files
  • Monthly runner cost: ~43 runner-hours
  • Speedup: 3.6x

After sharding (5 shards, duration-balanced):

  • Total CI time: 3 minutes 48 seconds
  • Each shard runs: 120-220 files (balanced by duration)
  • Monthly runner cost: ~32 runner-hours
  • Speedup: 4.9x

After sharding (10 shards, duration-balanced):

  • Total CI time: 2 minutes 12 seconds
  • Monthly runner cost: ~37 runner-hours
  • Speedup: 8.5x

The duration-balanced approach with 10 shards achieved an 8.5x speedup for roughly the same runner cost as the original single-runner setup. The time savings compound over a month: 100 PRs × 16.5 minutes saved = 27.5 hours of developer waiting time eliminated per month.

Caching Node Modules Across Shards

Without proper caching, each shard reinstalls dependencies from scratch, which can add 1-3 minutes to each job:

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # Caches ~/.npm based on package-lock.json hash

- run: npm ci  # Uses cached packages, runs in ~15s instead of 90s

For monorepos with many packages, cache the entire node_modules directory:

- name: Cache node_modules
  uses: actions/cache@v4
  id: cache-node-modules
  with:
    path: |
      node_modules
      packages/*/node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

- name: Install dependencies
  if: steps.cache-node-modules.outputs.cache-hit != 'true'
  run: npm ci

Handling Test Flakiness Across Shards

Sharding can surface flaky tests that were previously hidden. When a test fails in one shard but not others, and the failure is non-deterministic, you have a flaky test — not a sharding problem.

Add automatic retries to prevent flaky tests from blocking PRs:

- name: Run Jest shard ${{ matrix.shard }}/5
  run: npx jest --shard=${{ matrix.shard }}/5 --retries=2
  # Note: --retries is a custom Jest flag via jest-circus

Or configure retries in jest.config.js:

module.exports = {
  testRunner: 'jest-circus/runner',
  // Retry failed tests up to 2 times
  retryTimes: 2,
};

Tracking which tests are flaky across runs is where a tool like HelpMeTest earns its keep — it records pass/fail history across CI runs and surfaces tests with inconsistent results before they become a reliability problem.

Putting It All Together

A complete production-ready sharding workflow:

name: CI

on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: Test (shard ${{ matrix.shard }}/8)
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6, 7, 8]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Run tests
        run: |
          npx jest \
            --shard=${{ matrix.shard }}/8 \
            --coverage \
            --coverageDirectory=coverage \
            --forceExit \
            --ci

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-${{ matrix.shard }}
          path: coverage/coverage-final.json

  coverage:
    name: Merge Coverage
    needs: test
    runs-on: ubuntu-latest
    if: always()
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          cache: 'npm'
      - run: npm ci

      - uses: actions/download-artifact@v4
        with:
          pattern: coverage-*
          path: coverage-parts

      - run: |
          npx nyc merge coverage-parts coverage/coverage-final.json
          npx nyc report --reporter=lcov --temp-dir=coverage

      - uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

Summary

Test sharding in GitHub Actions is one of the most cost-effective performance improvements available for slow CI pipelines. The key points:

  • Use fail-fast: false to see all failures across shards
  • Duration-balanced splitting beats alphabetical splitting significantly
  • Merge coverage from all shards before reporting
  • Cache node_modules to avoid reinstallation overhead on every shard
  • Monitor for flaky tests that sharding can expose

Start with 4-5 shards and measure. For most projects, that alone delivers a 3-5x speedup. If your suite is still too slow, increase to 8-10 shards and implement duration-based splitting to keep all shards roughly equal.

Read more

Start now free