How to retry a failed GitLab pipeline (and when not to)

A red pipeline is the most common reason to open GitLab on a phone. Often the fix is one tap — a runner hiccuped, a registry timed out — and sometimes retrying just hides a real bug for another hour. Here is how to retry the right way, in GitLab’s current wording.

First, read the job log

Open the pipeline, then the failed job. The log tells you which kind of failure you have:

• Infrastructure: the runner lost its connection, a Docker image failed to pull, a network call timed out, the job was stuck. Retrying is the right move.
• Code: a test assertion, a compile error, a lint rule. Retrying will fail again and waste a runner. Fix the code, or tell the author.

GitLab’s log view has collapsible sections for each step, Show complete raw for the whole output, and per-line timestamps (generally available since GitLab 18.9).

Retry one job

On the failed job, select Run again. It works on any finished job — failed, passed or canceled — and creates a new job with a new ID. The old job and its log stay in the pipeline, so you keep the evidence.

Retry every failed job in a pipeline

On the pipeline, select Retry all failed or canceled jobs. Only those jobs run again; jobs that passed keep their results.

Run a manual job

A job with when: manual waits for a person — usually a deploy. Select Run (the play icon) on the job, or Run all manual for a stage. To pass variables, select the job’s name and use Run job. Running a manual job needs permission to merge to the job’s branch, and protected environments (Premium and Ultimate) can restrict it further.

Start a fresh pipeline

To run everything again from the top on the latest commit, go to Build › Pipelines › New pipeline. That button was called Run pipeline until GitLab 17.7; the Pipelines tab of a merge request still says Run pipeline.

Who is allowed to retry?

• At least the Developer role in the project to run, rerun or retry pipelines and jobs.
• On a protected branch, only people allowed to merge or push to that branch.
• Cancel is Developer and up by default (the minimum role is configurable); force cancel needs Maintainer.

If the button is missing or greyed out, it is almost always one of these.

Stop retrying flaky jobs by hand

If a job fails for infrastructure reasons often enough that people retry it by reflex, let GitLab do it. The retry keyword retries a job up to two times; retry:when limits it to the failures worth retrying, and retry:exit_codes to specific exit codes:

integration-tests:
  script: npm run test:integration
  retry:
    max: 2
    when:
      - runner_system_failure
      - api_failure

Avoid retry: 2 with no when on test jobs: by default every failure type is retried, which turns a real failing test into three slow failures. Note that stuck_or_timeout_failure was deprecated in GitLab 19.1 in favour of more specific reasons, so check the retry:when values for your version.

Retrying from your phone

Retrying is the perfect phone task: read the log, decide, tap. In MergeBell, pipelines and jobs open with live logs, and Retry, Cancel and Run for manual jobs are part of the free tier. With Pro, a pipeline watch on a branch sends a “Pipeline failed” push with a Retry button, and a followed pipeline shows its progress on the Lock Screen. Retry from a notification always runs on your phone with your own GitLab token, after Face ID on iPhone or once the phone is unlocked on Android.