How to Retry a Failing Job in GitLab CI

By Daniel Zoghalchali·Latchkey

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.

Frequently asked questions

How do I retry a Failing Job in GitLab CI?

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.

References

GitHub Actions documentation