The retry step runs a piece of your pipeline again when it fails, up to a number of times that you choose.

First, the basics

Jenkins is a free automation server that builds, tests, and delivers software. A pipeline is a written list of steps that Jenkins follows, stored in a text file called a Jenkinsfile. A step is one action in that list, such as “download the dependencies” or “run the tests.” When a step fails, the pipeline normally stops, marks the build as failed, and tells the team.

What retry adds

The retry step is a wrapper. You put other steps inside it, and you tell it how many attempts are allowed. If the steps inside succeed, the pipeline moves on. If they fail, the retry step runs them again from the beginning. Only when the last allowed attempt fails does the failure escape and stop the pipeline.

The key word is “transient”

A transient failure is a problem that goes away by itself, such as a brief network outage, a busy server, or a temporary lock. A permanent failure is a problem that stays until someone fixes it, such as a syntax error or a wrong password. Retry is a good answer for the first kind and a poor answer for the second.

What it gives you

• Fewer false alarms: one-second glitches no longer turn a build red.
• Less human effort: nobody has to click “rebuild” and wait again.
• Steadier pipelines: builds that depend on many outside systems become far more dependable.

Modern builds depend on dozens of outside systems, and outside systems occasionally stumble.

The old world

In the early days of automation, a build usually ran on one machine and used files that were already there. There was little to go wrong. As software grew, builds began to download libraries from the internet, pull container images from registries, talk to cloud services, and reach test databases. Every one of those connections is a small chance of failure.

The mathematics of many small risks

Suppose each outside call succeeds 99.5 times out of 100. That sounds excellent. But a pipeline with fifty such calls succeeds every time only about 78 times out of 100. In other words, more than one build in five fails for reasons that have nothing to do with the code. Teams call this build noise, and it slowly destroys trust: people start ignoring red builds.

The Pipeline answer

When Jenkins moved to Pipeline as code around 2016, the community added a small set of control-flow steps, and retry was among the first. It was intentionally simple: run this block again if it fails. Over the years, it has gained refinements, such as the ability to retry only for certain kinds of infrastructure trouble, like the loss of a build machine.

Real-world motivation

Large technology companies that publish about reliability engineering describe retries as a basic building block of distributed systems, from web browsers to cloud storage clients. Build pipelines are distributed systems too, so the same lessons apply, including the warning that careless retries can cause more harm than the failures they hide.

A handful of ideas explain almost everything about retrying well.

Vocabulary table

Retry is not a service or a plugin you install. It is a shape you give to a part of your pipeline.

The layers of a pipeline

A pipeline is made of stages, which are named phases such as “Build” and “Test.” Each stage holds steps. A wrapper step, like retry or timeout, holds other steps inside it. Wrappers can be placed inside each other, like nesting dolls. The order of the dolls changes the meaning.

flowchart TD
    P["Pipeline"] --> S["Stage Fetch Dependencies"]
    S --> R["Retry Wrapper with limit of 3 attempts"]
    R --> T["Timeout Wrapper for each attempt"]
    T --> B["Body Steps such as download command"]
    B -->|"Succeeds"| OK["Stage continues"]
    B -->|"Fails and attempts remain"| R
    B -->|"Fails on last attempt"| F["Failure reaches the stage"]
    F --> PF["Stage fails and build is marked failed"]

Reading the diagram

The stage contains a retry wrapper. Inside the retry sits a timeout, so every attempt gets its own time limit. Inside the timeout are the real steps. If the steps succeed, the stage continues. If they fail and attempts remain, control returns to the retry wrapper, which starts another attempt. Only when the final attempt fails does the failure travel outward to the stage, which fails, and the build is marked as failed.

Four places to use retry

Keep the wrapped area small

The smaller the retried block, the cheaper each retry is, and the fewer side effects can repeat. Wrap the one flaky action, not the whole stage that happens to contain it.

There is no magic here. The rules are few, and knowing them prevents most surprises.

Rule one: the count includes the first attempt

When you write a limit of three, the wrapped steps run at most three times in total. That is the original try plus up to two retries. Many beginners assume that three means “the first try plus three more,” which leads to confusion when they count attempts in the log.

Rule two: the body restarts from the top

Each attempt runs the entire wrapped block again from its first step. If the block has five steps and the fifth fails, all five run again. That is why small blocks are better than large ones: they repeat less work, and they repeat less that could be harmful to repeat.

Rule three: a failure is an exception

Inside Jenkins, a failing step raises an exception, a signal that says “something went wrong.” The retry wrapper catches it and decides whether to try again. A command that exits with a non-zero result also becomes such a failure, because the shell step turns it into one.

Rule four: a person aborting is not retried

If a human presses the abort button, retry does not fight it. The abort is respected, and the build stops. This is the correct behaviour, and it means retry cannot trap a build in a loop that people cannot escape.

Rule five: the final failure escapes

If the last allowed attempt fails, the failure propagates outward, exactly as if there had been no retry. The stage fails, and the build is marked failed. The log shows the earlier failures too, so you can see what happened.

Rule six: nothing is cleaned automatically

Retry does not clean the workspace, delete half-written files, stop leftover containers, or undo side effects. Whatever the failed attempt left behind is still there when the next attempt starts. Cleaning up is your job, and later chapters show how.

Follow one flaky download through three attempts and see what the pipeline does at every moment.

sequenceDiagram
    participant PL as Pipeline
    participant RT as Retry Wrapper
    participant BD as Body Steps
    participant SV as Remote Server
    PL->>RT: Enter block with limit 3
    RT->>BD: Attempt 1
    BD->>SV: Request package
    SV-->>BD: Connection reset
    BD-->>RT: Failure raised
    RT->>RT: Attempts remain so run again
    RT->>BD: Attempt 2
    BD->>SV: Request package
    SV-->>BD: Server busy
    BD-->>RT: Failure raised
    RT->>BD: Attempt 3
    BD->>SV: Request package
    SV-->>BD: Package delivered
    BD-->>RT: Success
    RT-->>PL: Block completes and pipeline continues

The lifecycle in plain steps

What the log looks like

The build log shows each attempt as a separate stretch of output, with the failure message at the end of each. The wrapper also prints a short note that it is retrying and how many attempts remain. When you investigate a strange build, read all the attempts, because the first failure usually holds the real cause.

Time adds up

Three attempts of ten minutes each mean thirty minutes of waiting before the pipeline can fail. Always think about the worst case, not just the lucky case.

Jenkins offers several places to put a retry. Each has a different reach.

The step form

The most common form is the retry step itself. You write its name, give it a number in brackets, and place the steps you want repeated inside braces after it. It works in both Declarative and Scripted pipelines, and it can be placed anywhere a step can go, including inside a stage, a parallel branch, or another wrapper.

The stage option

In Declarative Pipeline, a stage can carry an options section, and one of the available options is retry. Setting it tells Jenkins to run the entire stage again when the stage fails. This is convenient, but it repeats everything in the stage, including steps that were fine.

The pipeline option

The same option can be placed at the top of the pipeline, which retries the whole pipeline. This is rarely a good idea. A full pipeline can take an hour, and repeating it because of one blink in the last minute is wasteful.

The conditions form

Newer versions of the step accept a count together with a list of conditions, so it retries only for certain kinds of failure. Conditions are covered in their own chapter.

A helpful rule

Use the smallest form that solves your problem. Prefer a step around one flaky action to a stage option, and prefer a stage option to a pipeline option.

This is the most valuable chapter in the guide. A retry on the wrong failure hides bugs and wastes money.

flowchart TD
    F["A step failed"] --> Q1{"Is the cause outside your code"}
    Q1 -->|"No, a bug or bad config"| N1["Do not retry. Fix the cause"]
    Q1 -->|"Yes"| Q2{"Is it likely to pass on a later try"}
    Q2 -->|"No, such as wrong password"| N2["Do not retry. Report clearly"]
    Q2 -->|"Yes, such as timeout or busy server"| Q3{"Is the action safe to repeat"}
    Q3 -->|"No, it changes real data"| N3["Make it idempotent first or do not retry"]
    Q3 -->|"Yes"| Y["Retry with a limit, a timeout and a wait"]

Good candidates

Poor candidates

The safe-to-repeat question

Even a transient failure needs one more check: can the action run twice without harm? Downloading a file twice is harmless. Charging a customer twice is not. If an action changes real data and is not idempotent, retry may do damage, and the action needs redesign first.

Newer versions of the retry step can filter failures, so real bugs are not retried.

The problem with blanket retry

A plain retry treats every failure the same. A network blink and a compile error both trigger another attempt. The compile error will fail again, three times, and the team waits for no benefit.

The conditions idea

The step can be given a list of conditions together with its count. When conditions are given, the wrapper retries only if the failure matches one of them. Otherwise, the failure escapes immediately. Check the documentation for your Jenkins version, because the exact names and behaviour depend on the Pipeline plugin versions installed.

Conditions you may meet

Infrastructure versus application failures

A helpful way to think: conditions such as agent loss describe infrastructure failures, where the work itself was fine but the place it ran vanished. Those are almost always worth retrying. Application failures, where the work itself went wrong, usually are not.

A retry without a timeout is a trap. A hung attempt never fails, so the retry never gets to act.

The hung attempt problem

Retry reacts to failures. But some problems do not fail. They hang. A download that connects and then sends nothing can wait for hours. To the retry wrapper, the attempt is still in progress, so nothing is retried, and an agent stays busy for no reason.

The timeout wrapper

The timeout step sets a maximum time for the steps inside it. When the time is up, Jenkins stops the block and raises a failure. Placed inside the retry, the timeout gives every attempt its own limit, so a hung attempt is cut off, and the retry can try again.

Inside or outside?

Choosing the numbers

Set the per-attempt timeout to a comfortable multiple of the normal duration. If a download normally takes thirty seconds, five minutes is generous and still catches a hang. Set the outer limit so that the whole worst case still fits your patience: three attempts of five minutes plus waiting is about seventeen minutes.

Check your version’s behaviour

How a timeout interacts with retry can differ between Jenkins and plugin versions, especially about whether a timeout counts as a retryable failure. Always test it once with a deliberately hanging command in a safe job, and write down what happens.

Retrying instantly is often useless. If a server is overloaded, hitting it again a millisecond later just adds to the pile.

No built-in wait

The retry step starts the next attempt immediately. If you want a pause, you put a sleep step into the block, usually at the start of attempts after the first. Since the step does not tell the block which attempt it is on in most versions, people keep their own counter or write a small loop when they need growing waits.

Kinds of waiting

The retry storm

Imagine a package registry that hiccups for two seconds. Two hundred builds hit the error at once. All of them retry after exactly five seconds, and the registry, still recovering, receives two hundred requests in the same instant and fails again. This is a retry storm. Jitter spreads the retries out, and backoff thins them out over time.

Waiting for a condition instead

Sometimes you are not retrying a failure, but waiting for something to become ready, such as a newly created service. Jenkins has a waitUntil step that repeats a block until it returns true, with growing pauses between checks. It fits “wait for readiness” better than retry, which fits “repeat after failure.”

Jenkins offers several ways to deal with failure. Picking the right one avoids a lot of confusion.

When the tool’s own retry is better

Many command-line tools can retry by themselves. A download tool such as curl can repeat a request several times with waits, and package managers have settings for retries and timeouts. These retry at the level of one network request, which is finer and cheaper than repeating a whole block in Jenkins. Use them first when they exist, and use the Jenkins retry step for the parts they do not cover.

Try and catch: retry’s clever cousin

When you need different behaviour by kind of error, such as retrying on a server error but stopping at a permission error, a small loop with try and catch gives you full control. It is more code, so keep it in a shared library step where every pipeline can reuse it.

Do not confuse retry with ignoring

The catchError step and its cousins do not retry. They accept a failure and continue. That is right for optional steps such as uploading a report, and wrong for steps the build cannot live without.

Sometimes the trouble is spread across a whole build, and teams want the entire job to run again.

The Naginator plugin

The Naginator plugin adds a post-build action to Jenkins jobs, often labelled “Retry build after failure.” When a build fails, it schedules a new run of the same job. You can set the maximum number of reruns, choose whether waiting time between reruns is fixed or growing, and decide which failures qualify, for example only those whose log matches a chosen text. It was created for classic freestyle jobs, and it can also be used with some pipeline jobs.

Why whole-build retry is a blunt tool

• It repeats everything, including the stages that already passed.
• It hides the flakiness inside a single, long build rather than pointing at the flaky step.
• It multiplies cost: a one-hour build retried twice can consume three hours of agent time.
• Side effects such as deployments and published packages can be repeated.

When it still makes sense

Whole-build retry is defensible for older jobs that cannot easily be restructured, for nightly builds where extra time is cheap, or as a temporary bandage while a team fixes the real source of the flakiness. Set a small limit, a delay, and a matching rule so that only known transient failures trigger it.

Manual alternatives

The biggest danger of retry is not the wasted time. It is doing something twice that should have been done once.

What is idempotency?

An action is idempotent if doing it twice has the same effect as doing it once. Pressing the “floor five” button in an elevator ten times still takes you to floor five. Adding one to a counter ten times does not. Retry is only really safe around actions that behave like the first kind.

Actions that are usually safe to repeat

• Downloading a file or package.
• Reading data, or running a read-only check.
• Compiling code into a clean output folder.
• Uploading a file to a fixed name, replacing what was there.
• Setting a value to a specific state, such as “make sure this folder exists.”

Actions that are dangerous to repeat

• Sending emails or messages to customers.
• Charging money or creating orders.
• Appending lines to a shared file or log.
• Creating resources with generated names, so each attempt creates another one.
• Running a database change that is not written to be run twice.
• Incrementing version numbers, or tagging releases.

The half-done problem

A step can fail in the middle. The upload may have reached the server, but the confirmation was lost. From the pipeline’s point of view, the step failed. From the server’s point of view, the upload succeeded. A retry then uploads again. If the server rejects duplicates, the retry fails with a confusing “already exists” message. If it accepts duplicates, you now have two.

Making actions safe

Retry does not sweep the floor. If the first attempt leaves a mess, the second attempt walks into it.

What a failed attempt can leave behind

Cleaning strategies

• Start each attempt clean. Put cleanup at the beginning of the retried block, so it runs before every attempt, including the first. Deleting a temporary folder and recreating it is a common pattern.
• Use unique working folders per attempt, if the workspace makes cleanup awkward.
• Use unique names for containers and resources, so a leftover cannot block a new one.
• Clean in a failure handler, using try and finally logic or the post section, so that resources are released even when the block fails.
• Prefer disposable environments. A fresh container per attempt is the cleanest cleanup of all.

Locks and retries

If your block holds a lock, such as one taken with the lockable resources feature, decide whether the lock should cover all attempts or each attempt separately. Holding the lock across all attempts keeps others out for longer. Releasing between attempts lets somebody else slip in and change the state you were preparing. Neither is universally right, but the choice should be deliberate.

Wrapping a test stage in retry feels like an easy win. It is also the most misused application of the step.

What a flaky test is

A flaky test passes sometimes and fails sometimes on exactly the same code. Common causes include timing assumptions, shared test data, dependence on test order, outside services, and unpredictable resources like the clock or the network.

The temptation

Retrying the whole test stage makes red builds turn green, and the team’s pain goes away. But the flakiness is still there. It has just been hidden. Over time, the number of flaky tests grows, the retries grow, and build times grow with them. Worse, real bugs that fail intermittently get retried away, and they reach users.

The hidden cost

A better approach

Retrying looks harmless, but repeated actions can create security problems of their own.

Repeated wrong logins

Many systems lock an account after several failed logins. If a pipeline uses a wrong or expired password and retry runs the login three times, the account may be locked, and every other pipeline that uses it fails too. Never retry authentication failures. A rejected password will not become correct by waiting.

Rate limits and blocks

Servers that see many requests from one address may block it. A retry storm from a build farm can look like an attack. Respect rate-limit answers, wait as the server asks, and add backoff and jitter so your requests spread out.

Secrets in repeated logs

Every attempt writes to the build log. If a step prints details about the request, such as headers or command lines, three attempts print them three times. Make sure retried blocks do not print secrets, and that masking is active in each attempt.

Side effects with real consequences

A retried deployment step or message to a customer is not only a reliability problem. It can be a security and compliance problem too, for example a change that is applied twice and breaks an audit trail. Keep retried blocks away from sensitive actions unless they are designed for repetition.

Retry as a way to hide attacks

Intermittent failures can also be clues. A service that fails occasionally for a suspicious reason, such as intermittent certificate errors, may indicate a misconfiguration or an interception attempt. If retries always cover them up, nobody notices. Log retried failures and review them from time to time.

Every retry uses agent time, network capacity, and patience. At scale, small habits become big bills.

The cost of an attempt

If a block usually takes two minutes and fails three times before a lucky fourth attempt, it costs eight minutes of agent time, plus waiting. Multiply by hundreds of builds and dozens of stages, and retry can consume a noticeable share of your build capacity.

The retry budget

A retry budget is a limit on how much retrying is acceptable, for example “no more than five percent of attempts may be retries.” If retries exceed the budget, something is wrong in the underlying system, and the team must investigate rather than add more retries.

Practical guidance

Retries at scale

When the same outage hits hundreds of builds at once, retries multiply the load on the affected service. Build farms need a shared policy for backoff and jitter. A shared library step that every pipeline uses is the most practical way to enforce one policy across everything.

Root causes are cheaper than retries

Often the best performance improvement is to remove the cause of the transient failure: use a closer mirror, raise a connection limit, fix a slow database, or cache dependencies. Retry is the cheapest fix to write, and often the most expensive to keep.

Retry helps a pipeline survive small hiccups. It cannot replace a reliable system underneath.

What retry can survive

• Short network problems: a dropped connection heals within seconds.
• Busy services: a server that briefly refuses work recovers.
• Lost build machines: another machine can take over the block.
• Controller restarts: some steps cannot resume afterwards, and a retry can run them again.

What retry cannot survive

• Long outages: if a service is down for an hour, three attempts over two minutes all fail.
• Permanent faults: wrong configuration, missing permissions, or code bugs.
• Corrupted state: a retry cannot repair a broken database or a damaged cache.

Agent loss and resumability

Pipelines are built to pause and resume, so many steps survive a restart of the Jenkins controller. But a running shell command on a machine that vanished cannot continue. That failure is an infrastructure failure, and the conditions of the retry step exist for exactly this. With cloud and container agents that come and go, agent loss becomes a normal event that a good pipeline expects.

Combine retry with other defences

Fail loudly after the last attempt

A pipeline that swallows the final failure is worse than one that fails. Make sure that when all attempts are used, the build reports clearly, notifies the right people, and includes the reason from the last error.

A retry that nobody can see is a problem waiting to grow. Make retries visible.

Why visibility matters

Because retry turns failures into successes, a healthy-looking green dashboard can hide an unhealthy system. If half your builds need a second attempt, you are running on luck. Only measurement reveals it.

What to log

• The start of each retried block, with the limit.
• Each failure’s short reason, in plain words.
• The wait before the next attempt.
• The final result: succeeded on attempt two, or failed after three.

What to measure

Reading the numbers

Getting the data

Teams collect these measurements in several ways: by having a shared library step write a standard line to the log that a log system can count, by sending a small counter to a metrics system, or by reading build logs afterwards. A shared step that all pipelines use makes the data consistent.

Alerts

Alert the owning team when a step’s retry rate crosses an agreed threshold, when a retried block starts failing after all attempts, or when total retry time grows unusually. Do not alert on every single retry, because retries are working as designed.

Retry code is rarely tested, because it seems simple. That is exactly why it hides bugs.

Why test it?

Retry runs only when things go wrong, so mistakes in it appear only on bad days. A wrong count, a missing wait, or a cleanup that fails can turn a small glitch into a long outage. Test retry on purpose, on a quiet day.

Ways to test

Test shared library steps

If retry logic lives in a shared library step, it deserves unit tests with a pipeline testing framework, where you can simulate failures and check how many times the body ran and how long the waits were. Since this one step protects hundreds of pipelines, it deserves the best tests in your library.

Rehearse the outage

Once a quarter, deliberately break a dependency in a test environment, for example by blocking access to a mirror, and watch what happens to your pipelines. Do they retry sensibly? Do they fail with a clear message? Do the alerts fire?

When every team writes its own retry, you get dozens of styles. A shared library gives you one good one.

The problem with scattered retries

Without a common approach, one pipeline retries five times with no wait, another retries twice with a fixed wait, and a third has no retry at all. Some print helpful messages, and some print nothing. When an outage happens, some pipelines hammer the failing service, and others give up too early.

flowchart LR
    T1["Team A Jenkinsfile"] --> LIB["Shared Library Retry Step"]
    T2["Team B Jenkinsfile"] --> LIB
    T3["Team C Jenkinsfile"] --> LIB
    LIB --> POL["Standard Policy with limits, timeout, backoff and jitter"]
    POL --> CLS["Failure Classifier for transient or permanent"]
    CLS --> ACT["Retry with wait or fail fast"]
    LIB --> LOG["Standard Log Lines and Metrics"]
    LOG --> DASH["Dashboard and Alerts"]

What a standard retry step can do

• Apply a sensible default number of attempts and a per-attempt timeout.
• Add exponential backoff with jitter and a maximum delay.
• Classify failures as transient or permanent using known patterns, and fail fast on permanent ones.
• Print clear, uniform log lines for each attempt.
• Send a count to a metrics system.
• Refuse to wrap steps that are marked as unsafe to repeat.

Design guidelines

Cloud and configuration as code

Agents in the cloud come and go, and network calls cross many boundaries. Keep the retry defaults in the library and the library version in your configuration files, so a policy change reaches everyone through a reviewed release. Cloud teams often pair the pipeline policy with the retry settings built into their cloud tools, so that both layers cooperate rather than multiply.

Retry is one of the cheapest ways to make pipelines calmer, and one of the easiest to misuse.

Resilience versus honesty

Showing that a retry happened

One useful compromise is to let the build succeed after a retry, but record that a retry was needed, for example in the build description or as a marker in the results. Then the pipeline stays green, and the team still sees the cost.

There is no universal answer. A team with a very stable internal network needs little retry. A team that downloads from the public internet through many hops needs more. Match the design to your environment, your risks, and your patience.

A pattern is a solution many teams discovered independently. An anti-pattern is a trap many teams fell into.

Patterns worth copying

Anti-patterns to avoid

These are lessons that teams usually learn the hard way. You can learn them the easy way.

Best practices

• Retry only transient failures. Fail fast on bugs, bad configuration, and login errors.
• Keep the retried block small, wrapping one action rather than a whole stage.
• Use a timeout inside every retry that touches a network or a slow tool.
• Add a wait, ideally growing, with jitter and a cap.
• Keep attempts low, normally two or three.
• Make retried actions idempotent and start each attempt from a clean state.
• Prefer the tool’s own retry for single requests, and own only one retry layer.
• Log each attempt and never print secrets.
• Measure retry rate and save rate, and set a budget.
• Standardise in a shared library so all teams follow one policy.
• Fix root causes, using retry as a bridge, not a home.

Common mistakes and their fixes

Let us walk through a full improvement for a fictional team, step by step, without writing any code.

The situation

Harbourline Software has a web service pipeline with five stages: fetch dependencies, compile, unit tests, build a container image, and publish the image to a registry. About one build in six fails for no clear reason. Developers press rebuild without reading the log, and the on-call engineer has stopped trusting red builds.

Step by step

The result after one month

Many teams already have retries scattered around. Here is how to bring order without breaking builds.

What you may find

• A retry around the whole pipeline, added years ago by someone who has left.
• A stage option that retries a slow test stage five times.
• A hand-written loop with an unknown number of attempts and no wait.
• A whole-build retry plugin setting on old jobs.
• Tool-level retries inside scripts, combining with pipeline retries.

A safe migration path

The reward

After migration, every retry in your pipelines is deliberate, small, measured, and safe. Failures that remain are meaningful, and the team trusts red builds again.

A retry policy works best when the team agrees on it and reviews it together.

Agree on the defaults

Write down the standard number of attempts, the standard wait, the standard timeout, and where these are set. Put them in the contributing guide, so that every new pipeline follows the same rules.

Agree on what may be retried

• A list of actions that are approved for retry: downloads, uploads to fixed names, readiness checks.
• A list of actions that must never be retried without redesign: payments, customer messages, uncontrolled deployments.
• A rule that authentication and permission failures are never retried.

Agree on visibility

Every retry writes a standard log line and counts toward a shared metric. A weekly or monthly review looks at the top retried steps and asks what could remove the need.

Agree on ownership

The owner of the shared retry step decides defaults, reviews requests for exceptions, and publishes changes. Each team owns the retries in its own pipelines and answers for their numbers.

These scenarios show how organisations use retry. They are illustrative, so you can map them to your own situation.

What these examples share

In every good case, retry targets a known transient cause, sits around a small, safe block, has a timeout and a wait, and is measured. In the bad case, retry was broad, silent, and unmeasured, and it hid the very information the team needed.

Every modern automation system offers some way to deal with transient failure. Comparing them shows what is essential.

Feature sets change quickly, so check each tool’s current documentation before you rely on this table.

What Jenkins does differently

Jenkins gives you a small, general building block and expects you to compose a policy from it: timeouts, waits, conditions, and shared library steps. Some other tools bake failure categories into job settings. Jenkins gives more freedom and more responsibility, which is why a shared standard step is so valuable.

What is universal

The lessons apply everywhere: retry transient failures only, keep blocks small and safe to repeat, wait with backoff and jitter, cap attempts and time, own one retry layer, and measure how often retries save the build.

Once the basics feel comfortable, these ideas help larger teams and busier build farms.

Circuit breakers

A circuit breaker is a rule that stops trying a service that keeps failing. In an electrical panel, a breaker trips when there is too much current, protecting the wiring. In a pipeline, a breaker might say, “if the registry failed the last ten builds in a row, stop retrying and fail immediately with a clear outage message.” This saves time and reduces the load on the struggling service.

Failure classification

A custom retry step can look at the failure and decide what kind it is: a network error, a rate limit, a timeout, an authentication error, or a build failure. Each class gets its own treatment. Network errors get a retry with backoff. Rate limits get a longer, server-guided wait. Authentication errors and build failures fail at once. Keep the list of patterns small, tested, and documented.

Exit codes

Command-line tools report their result as a number called an exit code. Zero means success. Other numbers mean various kinds of failure, and some tools use specific codes for temporary problems. A custom step can capture the exit code and retry only for codes known to be transient.

Retry budgets across the pipeline

Instead of allowing three attempts per step, a pipeline might have a total budget, such as “at most five retries across the entire run.” When the budget is used up, the next failure fails immediately. This stops a sick run from consuming an hour of retries across many stages.

Idempotency keys

For actions that call outside services, send a unique key with each logical request, the same on every attempt. The service can recognise duplicates and process the request only once. Where a service supports keys, this makes retry safe even for actions like creating orders or launching cloud resources.

Hedging and other tricks

Some large systems send a second request if the first is slow, without waiting for failure, and use whichever answers first. This trades extra load for lower delay. It is rarely appropriate for build pipelines, but it shows the wider family of techniques that retry belongs to.

When something feels wrong, walk through these questions in order.

Every important word from this guide in one place, explained in plain language.

Short answers to the questions people ask most.

The retry step gives a pipeline a second chance. Used with judgement, it makes builds calmer. Used carelessly, it hides the very problems you need to see.

You began with a coffee machine that needed a second press and finished with a full policy for retrying pipeline steps. Along the way you learned how the count works, how the block restarts, how to add timeouts and waiting, how to tell transient failures from permanent ones, why idempotency and cleanup matter, and how to measure and standardise retries across a team. The main rules are simple: retry only transient failures, keep the block small, add a timeout and a wait, make the action safe to repeat, and measure what you rescue.