---
title: Auto-Retry
description: Automatically retry failed CI jobs to reduce false negatives caused by flaky tests and transient failures.
---

CI Insights Auto-Retry helps reduce false negatives in your CI pipeline by
automatically retrying failed jobs that may have failed due to flaky tests or
transient issues. This feature improves the reliability of your CI process
while providing insights into which jobs are consistently problematic.

## How Auto-Retry Works

When a CI job fails, Auto-Retry analyzes the failure based on configurable
rules to determine if it should be retried.

### Retry Process

1. **Detection**: Auto-Retry monitors workflow runs for job failures

2. **Rule Evaluation**: When jobs fail, the system evaluates them against your
configured retry rules

3. **Wait for Completion**: If any job matches a retry rule, Auto-Retry waits
   for the entire workflow to complete

4. **Workflow Retry**: Once complete, the workflow is retried,
   re-running either all failed jobs or the entire workflow

5. **Success Preservation**: In the default `job` mode, previously successful
   jobs are not re-executed

:::note
  Due to GitHub API limitations, Auto-Retry works at the workflow level: a
  matching job triggers a retry of the workflow run it belongs to, never of
  that job alone. Each rule picks how much of it re-runs (see
  [Retry Rules](#retry-rules)): in `job` mode only the failed jobs run again;
  in `pipeline` mode the whole run does, successful jobs included.
:::

## Benefits

- **Reduced False Negatives**: Automatically handle transient failures that
  don't represent real code issues

- **Improved Developer Experience**: Fewer interruptions from flaky test
  failures

- **Better CI Reliability**: More consistent build results across your pipeline

- **Data-Driven Insights**: Track which jobs are frequently retried to identify
  systematic issues

- **Time Savings**: Fewer manual retry actions and faster feedback loops

## Configuration

Auto-Retry uses a rule-based system to determine which workflow runs should be
retried. Rules are evaluated against individual jobs, but retries occur at the
workflow level. Each rule belongs to a single repository, chosen from the
repository selector at the top of the Auto-Retry page.

### Basic Setup

To set up Auto-Retry for a repository:

1. Navigate to your Mergify dashboard
2. Go to **CI Insights** → **Auto-Retry**
3. Pick a repository from the selector at the top of the page
4. Configure your retry rules for that repository

You can view, create, edit, or delete rules scoped to the selected repository.
Switch repositories from the selector to manage another one.

<Image src={ruleConfig} alt="CI Insights retry rule configuration" />

### Retry Rules

Auto-Retry rules define when a workflow should be retried based on job
failures. Each rule specifies:

- **Conditions**: When the job failure should trigger a workflow retry

- **Number of retries**: How many times a matching job may be retried, from 1
  to 10

- **Retry mode**: Whether to retry all failed jobs (`job`, the default) or the
  entire workflow (`pipeline`)

### Conditions

Conditions let you control which job failures should trigger a retry. Each
condition matches against a specific attribute of the failed job. Every rule
needs at least one condition, and when you combine several in a single rule,
all of them must match for the rule to apply.

The following condition attributes are available:

- **Job name**: Match against the name of the failed job. This allows you to
  target retries to specific jobs known to be flaky.

- **Pipeline name**: Match against the name of the workflow (pipeline) that
  contains the failed job.

- **Branch**: Restrict the rule to specific branches. You can also enter custom
  branch names that are not yet in the list.

- **Conclusion**: Match against the type of failure. Available values are
  `failure` (the job failed) and `timed_out` (the job exceeded its time limit).

- **Flaky**: Match against whether Mergify has detected the job as flaky.
  Set to `true` to only retry jobs that have been identified as flaky, or
  `false` to only retry jobs that are not considered flaky.

- **Log pattern**: Match against the content of the job logs and GitHub
  Actions check-run annotations using regular expressions. Each pattern is
  evaluated against individual log lines. You can specify multiple
  patterns; a retry is triggered if any of the patterns match. For
  example, `timeout|connection refused` would match any log line
  containing either "timeout" or "connection refused". The rule builder
  includes a **Test your log patterns** panel to check your log-pattern
  regex against sample log text before saving.