How to Retry Flaky Jobs in GitLab CI/CD

The retry keyword re-runs a job up to a set number of times, optionally only for specific failure reasons.

Set retry:max to the number of extra attempts and retry:when to the failure reasons that should trigger a retry, so you re-run on infrastructure flakes but not on real test failures.

Steps

• Add retry:max (0 to 2) for the number of automatic re-runs.
• Scope it with retry:when to specific failure reasons.
• Reserve retries for transient causes, not genuine bugs.

Pipeline

e2e:
  script: npm run test:e2e
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
      - api_failure

Gotchas

• retry:max is capped at 2, so a job runs at most three times.
• Retrying real test failures masks bugs; restrict when to infrastructure reasons. Latchkey managed runners auto-retry transient infrastructure failures for you.

Related guides