---
title: "Flaky Jest tests on GitHub Actions: setup, retries and runner pitfalls"
description: "Run Jest with Mergify Test Engine on GitHub Actions: the withMergify setup, jest.retryTimes versus Re-run failed jobs, and what makes Jest flake on GitHub-hosted runners."
url: https://mergify.com/learn/flaky-tests/github-actions/jest
---

[Learn](https://mergify.com/learn)/[Flaky tests](https://mergify.com/learn/flaky-tests)/[GitHub Actions](https://mergify.com/learn/flaky-tests/github-actions)/Jest

# Flaky Jest tests on GitHub Actions.  
Set up, retried right, quarantined.

On GitHub Actions, Jest needs one package, one wrapper and one secret: install `@mergifyio/jest`, wrap your config with `withMergify`, and give the test step a `MERGIFY_TOKEN`. The reporter uploads every result when the run ends and applies quarantine inside Jest's workers, with no JUnit file to write or upload.

By [Julien Danjou](https://mergify.com/about), Co-founder & CEO of MergifyUpdated October 28, 2026

Setup

## Run Jest with Test Engine on GitHub Actions

Create a Mergify application key with the `ci` scope and store it as the `MERGIFY_TOKEN` secret. Then:

`jest.config.js`: Wrap the Jest config with withMergify, which adds the reporter and test runner.

```
const { withMergify } = require("@mergifyio/jest");

module.exports = withMergify({
  testEnvironment: "node",
  // ...your existing configuration
});
```

`.github/workflows/ci.yml`: Pass the MERGIFY\_TOKEN secret to the step that runs Jest.

```
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - name: Run tests
        env:
          MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
        run: npm test # jest
```

-   Remove `--reporters` from the test command. On the command line it replaces the reporters of your config, the Mergify one included.
-   Config in `package.json`? `withMergify` needs a function call, so move it to `jest.config.js` first.
-   Moving from `jest-junit` and the upload action? Drop the upload step and `continue-on-error` from the test step: the reporter sends the results and quarantine is already in Jest's exit code.
-   Running Jest across a matrix? Every leg reports the same `GITHUB_JOB`, so set `MERGIFY_TEST_JOB_NAME: test (${{ matrix.node-version }})` on each leg. Without it, the legs' results merge into one test, and a test that only fails on one version looks flaky instead of broken.

Full reference: [Jest on docs.mergify.com](https://docs.mergify.com/test-engine/test-frameworks/jest).

Retries

## Re-run failed jobs versus retrying the test

GitHub Actions retries at the job level. Re-run failed jobs, or `gh run rerun --failed`, starts the failed jobs again with the same `GITHUB_SHA` and `GITHUB_REF`, up to 30 days after the run and up to 50 times per run. Each attempt repeats the whole job: checkout, toolchain setup, dependency install, then every test, including the ones that passed.

Re-run failed jobs repeats `npm ci` and every test file for one test that may have been unlucky.

`jest.retryTimes(2)` retries inside the run and reports the test as passed when an attempt succeeds. The flake is still there, and only the log of that run shows the failed attempts.

`@mergifyio/jest` turns Jest's own retries off during its reruns and decides with history instead. On a pull request it reruns the tests the target branch does not have yet, in Jest's workers, within the Prevention budget, and fails the run if any attempt fails. On the default branch it reruns the tests Test Engine knows as unhealthy without changing the result.

Runners

## Why Jest tests flake on GitHub Actions

1.  ### One worker on a private-repository runner
    
    Jest's `maxWorkers` defaults to the number of CPUs minus one. On a [2-vCPU private runner](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) that is a single worker, so files that ran in parallel on your laptop run one after the other, and a slow file can push tests past the default 5-second timeout. On a public repository's 4 vCPUs it is three workers. Reproduce with the runner's count.
    
    ```
    npx jest --maxWorkers=1
    ```
    
2.  ### Workers running out of memory
    
    A private runner has 8 GB for the runner, your app's services and every Jest worker. Workers that leak memory across files get killed mid-file, and the failure lands on whichever test was running. `workerIdleMemoryLimit` recycles a worker before it gets there.
    
    ```
    module.exports = withMergify({
      workerIdleMemoryLimit: "512MB",
    });
    ```
    
3.  ### Snapshots that only exist on one machine
    
    Jest runs with `--ci` by default on GitHub Actions, where a missing snapshot fails the test instead of being written. A test whose snapshot was never committed passes locally and fails on CI, and goes "green" the moment someone commits it. It looks flaky; it is a missing file.
    

The missing layer

## GitHub Actions doesn't know what a test is.

GitHub Actions tells you a job failed. Test Engine tells you which Jest test failed, whether it failed on the same commit before, and whether it should block the merge. Read [what Test Engine adds to GitHub Actions](https://mergify.com/learn/flaky-tests/github-actions), or the [Jest guide](https://mergify.com/learn/flaky-tests/jest) for the patterns behind flaky Jest suites on any CI: fake timers, snapshot drift, and the async traps behind flaky Jest suites.

## Other frameworks on GitHub Actions

-   [pytest](https://mergify.com/learn/flaky-tests/github-actions/pytest)
-   [Vitest](https://mergify.com/learn/flaky-tests/github-actions/vitest)
-   [Playwright](https://mergify.com/learn/flaky-tests/github-actions/playwright)
-   [RSpec](https://mergify.com/learn/flaky-tests/github-actions/rspec)
-   [Go](https://mergify.com/learn/flaky-tests/github-actions/go)
-   [Cypress](https://mergify.com/learn/flaky-tests/github-actions/cypress)
-   [JUnit](https://mergify.com/learn/flaky-tests/github-actions/junit)
-   [TestNG](https://mergify.com/learn/flaky-tests/github-actions/testng)
-   [Minitest](https://mergify.com/learn/flaky-tests/github-actions/minitest)
-   [MSTest](https://mergify.com/learn/flaky-tests/github-actions/mstest)
-   [NUnit](https://mergify.com/learn/flaky-tests/github-actions/nunit)
-   [Pest](https://mergify.com/learn/flaky-tests/github-actions/pest)
-   [PHPUnit](https://mergify.com/learn/flaky-tests/github-actions/phpunit)
-   [Rust](https://mergify.com/learn/flaky-tests/github-actions/rust)

## Frequently asked questions

Why are my Jest tests flaky only on GitHub Actions?

Look at the runner first: one worker on a 2-vCPU private runner instead of one per core on your laptop, 8 GB shared by every worker, and a UTC clock. Run with --maxWorkers=1 and TZ=UTC locally to reproduce.

Do I still need jest-junit?

Not for Test Engine: @mergifyio/jest uploads the results itself. If another tool reads the JUnit file, list jest-junit in the config's reporters, after which withMergify adds its own.

Are test.concurrent tests rerun?

No. jest-circus starts them together with the other tests of their file and cannot run one again on its own. They are still reported and can still be quarantined.

## Catch the flaky Jest tests in your GitHub Actions runs.

Mergify merges more than half a million pull requests a month without breaking main.

[Start a free 14-day trial](https://dashboard.mergify.com/)[Read the setup docs](https://docs.mergify.com/test-engine/test-frameworks/jest)
