Skip to content
Latchkey

How to Retry a Failing Job in GitLab CI

GitLab retries a failing job automatically with the retry keyword, optionally scoped to specific failure types.

Set retry: to a max count, or use the object form with when: to retry only on certain failures (e.g. runner_system_failure, api_failure).

Retry only transient failures

Retry up to twice, but only for runner/system failures and script-timeout - not real test failures.

.gitlab-ci.yml
flaky-integration:
  script:
    - npm run test:integration
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
      - api_failure

Gotchas

  • A bare retry: 2 retries on any failure, which can mask real bugs - scope it with when: where possible.
  • max is capped at 2 (so up to 3 total runs); higher values are rejected.
  • Retries re-run the whole job from scratch - non-idempotent side effects repeat.

Related guides

How to Retry a Failing Step in GitHub ActionsRetry a flaky step in GitHub Actions with a retry action or a bash loop with backoff, so transient network an… How to Set a Job Timeout in GitLab CISet a job timeout in GitLab CI with the timeout keyword, how it interacts with the project and runner timeout…
Run this faster and cheaper on Latchkey managed runners. Start free →