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 }}/5This 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/5Jest 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: 1Vitest 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 --coverageOne 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.jsonStatic 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_FILESMerging 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: trueFor 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.jsonReal 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 90sFor 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 ciHandling 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-circusOr 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.infoSummary
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: falseto see all failures across shards - Duration-balanced splitting beats alphabetical splitting significantly
- Merge coverage from all shards before reporting
- Cache
node_modulesto 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.