Before exploring the mechanics, it’s worth clearly separating this from simply re-running a pipeline entirely.

A full re-run versus a partial restart

A full re-run starts a brand-new pipeline execution from the very first stage, exactly as if the pipeline were being triggered for the first time — every stage runs again, regardless of whether it previously succeeded. Restarting from a specific stage is different: it resumes an existing, previously failed run, skipping every stage that already completed successfully and beginning execution again only from a chosen, later point.

Where this capability comes from in Jenkins

This capability is available for declarative pipelines that define their work as a named sequence of stages, and Jenkins exposes it directly from a failed build’s own page — an option to restart the pipeline beginning at any one of its previously defined stages, rather than only offering a single, all-or-nothing “run again” choice.

The rest of this tutorial explores exactly what makes this capability genuinely useful, and equally important, what makes it something to use thoughtfully rather than reflexively.

This feature exists because, for many pipelines, a full re-run after a failure is wasteful in a very concrete, measurable way.

The cost of redoing already-successful work

A long pipeline might spend twenty minutes building an application, another fifteen minutes running an extensive test suite, and only then reach a five-minute deployment stage that happens to fail due to a temporary, unrelated network issue. A full re-run means redoing the entire thirty-five minutes of already-successful build and test work, purely to retry the five minutes that actually failed.

Faster recovery from transient, isolated failures

Many pipeline failures are transient and specific to one stage — a temporary network blip during deployment, a flaky external service during a particular test, a momentarily unavailable artifact repository — and restarting from that specific stage lets a team recover from exactly this kind of isolated hiccup in a fraction of the time a full re-run would take.

Reducing unnecessary load on shared infrastructure

Beyond simply saving time, avoiding unnecessary full re-runs also reduces load on shared build agents and any external systems the earlier stages interact with — a meaningful consideration in an organization where many pipelines are competing for the same limited pool of infrastructure.

Not every pipeline is automatically eligible for this capability — a few specific ingredients need to be in place.

Named, declarative stages as the foundation

For Jenkins to offer a restart option at a specific stage, the pipeline must be written using the declarative syntax’s named stage structure, since these named boundaries are exactly what Jenkins presents as the available restart points — a pipeline without this clear stage structure has no natural points to restart from at all.

What a restart actually skips, and what it doesn’t

When restarting from a chosen stage, Jenkins skips executing every stage before it entirely — it doesn’t quietly re-verify that earlier stage’s success; it simply trusts the original run’s recorded outcome and proceeds directly to the chosen stage’s logic, executing it as a fresh, brand-new attempt.

Where workspace state comes into the picture

Because a restarted stage begins in whatever workspace state exists from the original run, whether that state genuinely reflects what a from-scratch run at that point would have produced is a critical, and sometimes surprising, factor in whether the restart behaves correctly — a concern explored in depth in the chapter on idempotency later in this tutorial.

Understanding the internal mechanics clarifies exactly what Jenkins does, and doesn’t, verify during a restart.

The moment a restart is requested

When a user selects a specific stage to restart from, Jenkins creates a new build record — distinct from, but linked to, the original failed run — and begins executing the pipeline’s declared logic starting at that chosen stage, using the original run’s recorded checkpoint data to determine exactly which stages should be treated as already complete.

sequenceDiagram
    participant U as User
    participant J as Jenkins
    participant Orig as Original Failed Run
    participant New as New Restarted Run
    U->>J: Select "Restart from Stage: Deploy"
    J->>Orig: Reference recorded checkpoint data
    J->>New: Create new build, marked as a restart
    New->>New: Skip Checkout, Build, Test (trusted as already successful)
    New->>New: Execute Deploy stage fresh
        

What the new build inherits from the original

The restarted build typically inherits the same parameters, the same triggering commit, and, depending on how the underlying agent and workspace are managed, potentially the same workspace on disk — meaning files left behind by the original run’s earlier, successful stages may still be physically present when the restarted stage begins executing.

No re-verification of earlier stages, by design

It’s worth being explicit that Jenkins does not re-run any correctness checks on the skipped, earlier stages during a restart — it simply trusts that they succeeded, exactly as recorded, and proceeds directly to the chosen stage. This design choice is precisely what makes restart fast, but it’s also precisely why restart isn’t automatically safe for every kind of pipeline, a distinction covered in depth in Chapter 7.

Following one failed build through a restart shows exactly what data carries forward, and what’s regenerated.

What flows forward from the original run

Beyond simply the recorded knowledge of which stages already succeeded, whatever a skipped stage physically produced — a compiled artifact sitting in the workspace, an environment variable set earlier in the run — potentially carries forward into the restarted execution, since the restart doesn’t reset the workspace to a truly clean, blank state by default.

Different kinds of failures call for genuinely different restart decisions.

Recognizing which scenario you’re actually in

Correctly diagnosing which of these categories a given failure falls into — genuinely transient versus a real underlying code problem — is the single most important judgment call in deciding whether a stage restart is the right response, or whether a fresh, full pipeline run is actually necessary instead.

This single concept determines, more than any other, whether restarting a given pipeline from a given stage is actually safe.

What idempotency means, in plain terms

A stage is idempotent if running it again produces the same correct result regardless of whether it’s the first attempt or a later retry — and critically, regardless of whether earlier stages ran moments ago in this same execution, or hours ago in an original run being restarted from. An idempotent deployment stage, for example, safely re-deploys the exact same version without causing any harm if run a second time.

Why a restarted stage’s assumptions can quietly be wrong

A stage restart trusts that everything before it happened exactly as the workspace and build record suggest — but if a stage isn’t genuinely idempotent, or if something in the environment changed between the original failed attempt and the restart, that trust can be misplaced, leading to subtly incorrect or even harmful behavior that a from-scratch run would never have produced.

Designing pipelines with restart safety in mind from the start

Rather than discovering idempotency problems only after an accidental duplicate action, deliberately designing stages to be safely repeatable — checking whether an action has already been performed before performing it again, for example — pays off significantly the first time an unexpected failure makes a stage restart genuinely useful.

Stage restart offers genuine efficiency benefits, but those benefits only materialize under the right conditions.

The risk of using restart as a substitute for investigation

It’s tempting to reflexively restart a failed stage without genuinely understanding why it failed, especially when restart is fast and convenient — but doing this repeatedly, for a stage that’s actually failing for a real, recurring reason, simply delays a genuine fix while consuming everyone’s patience with an increasingly unreliable pipeline.

Because restart bypasses re-running earlier stages, it carries specific security implications worth understanding.

Restart and stages that perform security-relevant checks

If an earlier, skipped stage was responsible for a security-relevant check — such as a static analysis scan or a dependency vulnerability check — a restart trusts that check’s original result without repeating it, meaning if something in the environment or the scanning tool’s own database changed since the original run, the restarted build proceeds without benefiting from that update.

Restarting past an approval gate

Special care is warranted around restart behavior involving manual approval gates — an organization’s policy should be explicit about whether restarting from a stage after an approval gate genuinely requires that approval to be granted again, or whether it silently reuses the original approval decision, since these have very different security implications.

Auditing restarted builds distinctly from fresh runs

Because a restarted build skips genuine re-execution of its earlier stages, maintaining a clear, visible distinction in build history and audit logs between a fresh, full run and a restarted one helps anyone reviewing that history understand exactly what was, and wasn’t, actually re-verified for that specific deployment or release.

Tracking how restart is actually being used across an organization reveals both its benefits and any misuse.

Tracking restart frequency by stage

Recording how often each specific stage across the organization’s pipelines is restarted reveals which stages are chronically unreliable and worth genuinely fixing, distinct from those experiencing only rare, truly transient issues that restart handles perfectly well.

graph TD
    A[Restart Triggered] --> B[Stage and Reason Logged]
    B --> C[Restart Frequency Dashboard]
    C --> D[Chronically Unreliable Stages Flagged]
    D --> E[Team Investigates Root Cause]
        

Distinguishing healthy restart usage from a symptom of a deeper problem

A low, occasional rate of restarts for a specific stage is generally a healthy sign of the feature working exactly as intended, while a high, persistent rate of restarts for that same stage is a strong signal that the stage itself has a real, recurring problem deserving direct investigation rather than repeated restarting.

A handful of recurring design choices separate pipelines that support restart gracefully from ones where restart quietly causes harm.

Pattern: designing every stage to be genuinely idempotent

As discussed in Chapter 7, deliberately designing every stage — especially ones with real-world side effects like deployments or notifications — to be safely repeatable is the single most important design choice supporting safe, worry-free restart across an entire pipeline.

Anti-pattern: a notification stage with no duplicate protection

A stage that sends a one-time notification — announcing a release, for example — with no mechanism to detect and prevent a duplicate send, will fire that same notification again every time the pipeline is restarted from that point, quickly becoming confusing or annoying for anyone receiving it.

Pattern: keeping stages small and focused

Following the same general pipeline-design principle discussed elsewhere in this guide, smaller, more focused stages give restart much finer-grained control — a pipeline with one enormous, all-encompassing stage offers no meaningful restart granularity at all, while several smaller stages let a restart skip precisely the work that already succeeded.

These are the lessons most teams learn only after a restart has caused an unexpected duplicate action or a confusing outcome.

Common mistake: restarting a stage that depends on a fresh, clean workspace

Some stages genuinely need a completely clean starting state to behave correctly, and restarting into a workspace still holding leftover files or state from the original run’s earlier stages can cause subtle, hard-to-diagnose problems that wouldn’t occur in a genuinely fresh, full pipeline run.

Common mistake: treating restart frequency data as unimportant

Ignoring how often a specific stage is being restarted across the organization misses a valuable, freely available signal about which parts of the shared pipeline infrastructure genuinely need attention, rather than continuing to quietly rely on restart as an ongoing workaround.

Recognizing the boundaries of this feature is just as important as understanding how to use it.

When the underlying code itself is the problem

If a stage failed because of an actual defect in the application code being built or tested, restarting that same stage will simply fail again in exactly the same way, since nothing about the underlying cause has changed — in this situation, the code needs to be fixed and a genuinely fresh pipeline run triggered against the corrected version.

When the environment has meaningfully changed since the original run

If significant time has passed since the original run, or if the target environment or dependencies have meaningfully changed in the interim, the assumptions a restart relies on — that everything up to the chosen stage is still valid and current — may no longer hold, making a fresh, full run the safer, more trustworthy choice.

Establishing organizational guidance on when to restart versus rerun

Providing pipeline authors and operators with clear, simple guidance — a short decision checklist covering failure type, elapsed time, and stage idempotency — helps ensure restart is used specifically where it genuinely helps, rather than being applied reflexively to every failure regardless of its actual underlying cause.

Seeing how different kinds of organizations apply stage restart makes the concept concrete.

A common thread across all four examples

In each case, the organization treats stage restart as a genuinely powerful capability that deserves deliberate design and clear policy, rather than an incidental convenience used without much thought — recognizing that its real value depends entirely on the discipline surrounding how and when it’s actually used.

Straightforward answers to the questions almost every newcomer to pipeline stage restart asks.

No — as explained in Chapter 4, Jenkins trusts the original run’s recorded outcome for earlier stages without re-running or re-verifying them, which is exactly what makes restart fast but also why it requires careful judgment.

Not necessarily — as discussed in Chapter 7 and Chapter 13, safety depends heavily on whether that stage, and any stage after it, is genuinely idempotent, and on whether the underlying failure was actually transient rather than a real code defect.

As covered in Chapter 5, they typically remain present when the restarted stage begins, meaning the restarted execution isn’t necessarily starting from a completely clean, blank workspace.

This should be an explicit organizational policy decision, as discussed in Chapter 9 — many organizations require a fresh approval specifically to avoid an old decision being implicitly reused under different circumstances.

As covered in Chapter 10, tracking restart frequency by stage and watching for a persistently high rate for any specific stage is the recommended way to spot a stage that needs genuine investigation, rather than continued restarting.

As discussed in Chapter 13, a significant time gap increases the risk that the original run’s assumptions no longer hold, so a fresh, full re-run is often the safer, more trustworthy choice in that situation.

Restarting a Jenkins pipeline from a specific stage is a genuinely powerful capability for recovering quickly from failures that are isolated, transient, and unrelated to the actual correctness of everything that ran before them. By trusting an earlier run’s recorded success and resuming execution only from a chosen point, it can turn a lengthy, wasteful full re-run into a fast, targeted recovery — saving time, reducing load on shared infrastructure, and speeding up the feedback loop for diagnosing whether a failure was ever anything more than a passing hiccup. But that same trust is precisely where its risk lives: a stage restart offers no re-verification of what came before it, which means its safety depends entirely on how deliberately a pipeline’s stages were designed. Idempotent stages, clear policy around approval gates, and honest, ongoing attention to which stages are restarted most often are what separate an organization genuinely benefiting from this capability from one quietly accumulating duplicate notifications, stale approvals, and unresolved flakiness behind a comfortable, convenient shortcut.