A stage is a named block of work inside a Jenkins pipeline. It groups together a set of related steps and gives that group a clear label such as Build, Test, or Deploy.

Start with two words you may already know. A pipeline is the full assembly line that takes your code from a programmer’s laptop all the way to real users. A step is one small action, such as running a command, copying a file, or sending a message. A stage sits in the middle: it is a group of steps that together achieve one goal.

So the picture looks like this. A pipeline holds several stages. Each stage holds one or more steps. Steps do the real work, while stages give that work a shape, a name, and a place on the screen.

What a stage gives you

• A name. People can talk about “the Test stage” instead of “that middle bit of the script”.
• A visible box. Jenkins draws every stage on the job page, so anyone can see which phase is running, which finished, and which failed.
• A boundary for control. You can set conditions, time limits, and special machines for one stage without touching the others.
• A place to measure. Jenkins records how long each stage took, so slow phases are easy to spot.

To see why stages matter, imagine life without them.

Before pipelines became popular, many teams used a single long job that ran one big list of commands from top to bottom. When such a job failed, the team faced a wall of thousands of log lines and had to search for the spot where things broke. Was it the compile? The tests? The upload? Nobody could tell at a glance.

That old way caused three troubles. First, it was hard to read, because the whole process was one shapeless blob. Second, it was hard to fix, because a failure gave no clue about where to look first. Third, it was hard to improve, because nobody knew which part was slow. Stages solve all three at once by chopping the blob into named, measurable pieces.

A few neighbouring words appear again and again when people talk about stages. Learn them together.

Two styles of writing pipelines

Jenkins lets you write pipelines in two styles. Declarative is a tidy, structured layout with a fixed shape: it has a clear place for the agent, for a list of stages, and for actions to run afterwards. Scripted is a free-form style built on a real programming language called Groovy, which is more powerful but easier to make messy.

Stages exist in both styles, but they behave a little differently. In declarative style, stages are a required part of the structure, and Jenkins checks them carefully. In scripted style, a stage is simply a named block that you may place wherever you like, and it is mainly used for labelling and display. Most beginners and most teams should start with declarative style.

Let us place stages inside the bigger Jenkins picture so you can see who does what.

A Jenkins system has one controller, which is the brain, and many agents, which are the hands. The controller reads the Jenkinsfile, understands the stages, keeps track of their progress, and shows the result in the web page. The agents run the real steps. When you split a pipeline into stages, the controller can hand each stage to a suitable agent and watch it carefully.

flowchart LR
  DEV["Developer"] -->|"push code"| REPO["Git Repository"]
  REPO -->|"webhook"| CTRL["Jenkins Controller"]
  CTRL -->|"reads Jenkinsfile"| PIPE{"Pipeline"}
  PIPE --> S1["Stage: Build"]
  PIPE --> S2["Stage: Test"]
  PIPE --> S3["Stage: Package"]
  PIPE --> S4["Stage: Deploy"]
  S1 -->|"runs on"| A1["Agent 1"]
  S2 -->|"runs on"| A2["Agent 2"]
  S3 -->|"runs on"| A1
  S4 -->|"runs on"| A3["Agent 3"]
  A1 --> ART["Artifact Storage"]
  CTRL -->|"shows progress"| VIEW["Stage View Screen"]

Walking through the picture

A developer pushes code to the Git repository. The repository sends a small message called a webhook (an automatic “something changed!” notification over the web) to the controller. The controller reads the Jenkinsfile and finds four stages. It places each stage on a matching agent. Stage 1 and Stage 3 happen to use the same agent, so they share one workspace. Stage 2 uses another agent, perhaps because it needs special tools. The last stage runs on a third agent that is allowed to reach the real servers. Meanwhile the controller draws all of this on the Stage View screen, so people can watch.

Before we study a stage on its own, let us see where it sits in the whole structure.

A declarative pipeline has a fixed shape with a few named parts. Think of it as a form with labelled boxes.

Inside the stages part, every individual stage has a name and its own inner contents. Inside each stage there must be a steps part, which lists the real actions. A stage may also carry its own optional settings, such as which agent to use, which conditions must be true, and which actions to run after that stage only.

Let us follow one pipeline from the doorbell ringing to the final report, paying attention to what happens around each stage.

sequenceDiagram
  participant C as Jenkins Controller
  participant Q as Build Queue
  participant A as Build Agent
  participant V as Stage View
  C->>C: Load and validate Jenkinsfile
  C->>Q: Request executor for Stage 1
  Q->>A: Assign free executor
  C->>C: Check stage condition
  A->>A: Run steps in order
  A-->>C: Send logs and result
  C->>V: Update stage box and timing
  C->>Q: Request executor for Stage 2
  Note over C,A: Repeat until all stages finish or one fails

A clever trick: saved progress

Pipelines can run for hours, and computers sometimes restart. Jenkins saves the state of a running pipeline to disk as it goes, stage by stage. After a controller restart, the pipeline can usually continue from where it stopped instead of starting over. Think of saving your game at each checkpoint.

The automatic first stage

If your pipeline downloads code from a repository automatically, you may notice an extra stage on the screen with a name that starts with the word “Declarative”, such as the checkout of source code. Jenkins adds it for you. It is a helper stage, not one you wrote. Another helper appears at the end when the pipeline has post actions. Do not be surprised by these guests.

Stages often need to hand things to each other, such as a finished program package. How does that work?

When two stages run on the same agent, they share the same workspace folder. A file created in the Build stage is simply still there when the Test stage starts. This is the easiest situation.

When two stages run on different agents, the second agent has its own empty workspace. The files from the first agent are not there. Jenkins offers a tool for this called stash and unstash. Stash means “put these files in a temporary box on the controller”. Unstash means “take the files out of that box on another agent”. It works well for small or medium files. For big files, teams store the results in an artifact repository, a warehouse for finished packages, and let later stages download them from there.

flowchart LR
  B["Build Stage on Agent 1"] -->|"stash files"| BOX[("Temporary Box on Controller")]
  BOX -->|"unstash files"| T["Test Stage on Agent 2"]
  B -->|"upload package"| REPO[("Artifact Repository")]
  REPO -->|"download package"| D["Deploy Stage on Agent 3"]

Every stage needs a machine. You can pick one for the whole pipeline or a different one for each stage.

The agent setting decides which machine runs the work. If you set it at the very top of the pipeline, every stage uses it. If you instead set the top-level agent to “none” and give each stage its own agent, every stage chooses the machine that suits it best.

Agents can be described in several ways. You can ask for any free agent, or an agent that carries a certain label such as “linux” or “windows”, or a fresh temporary container created just for that stage. A container is a small, sealed box that holds a program and everything it needs, and it disappears when the stage ends. This gives every stage a clean room with the exact tools it requires.

A stage can carry extra settings that decide whether it runs, how long it may take, and what it needs.

The “when” condition in more detail

The when setting is one of the most useful stage controls. It lets one Jenkinsfile handle many situations. A stage that publishes a release can carry a condition that says “only on the main branch”, so ordinary feature branches skip it. When a condition is false, the stage is drawn as skipped and no steps run.

Conditions can check the branch name, whether the build was started by a tag, the value of an environment name, whether certain files changed, or even a small custom test. They can also be combined with “all of”, “any of”, and “not” for finer control. By default, Jenkins checks the condition before it starts the stage’s agent and before it asks for approval, which avoids wasting machines on stages that will be skipped.

Manual approval stages

Many teams place an approval gate before the final deployment. A stage with an input setting pauses and shows a button on the screen. A permitted person can approve or abort. This keeps humans in charge of risky moves such as sending a change to real users, while everything before it stays automatic.

Normally stages run one after another. But some work does not depend on each other, and can happen at the same time.

Imagine you must test your program on three different systems. Running the three checks one by one would take three times as long. If you have enough machines, you can run them in parallel, meaning at the same moment. Jenkins lets you place several stages inside a parallel block. They start together, and the pipeline moves on only when all of them finish.

flowchart LR
  B["Build"] --> P{"Parallel Tests"}
  P --> T1["Test on Linux"]
  P --> T2["Test on Windows"]
  P --> T3["Test on Mac"]
  T1 --> J["Join Results"]
  T2 --> J
  T3 --> J
  J --> D["Deploy"]

Fail fast

By default, if one parallel stage fails, the others keep running until they finish. If you would rather stop everything immediately, there is a fail fast option. When any parallel branch fails, the rest are aborted at once. This saves time and machines when a single failure already means the whole result is bad.

Sequential stages and nesting

Stages can also be placed inside other stages. A stage can hold a group of smaller stages that run in order, and a parallel group can contain such groups. This lets you build layouts like “in parallel, do Linux work and Windows work, where each of those has its own Build and Test in sequence”. Use nesting carefully, because deep nesting quickly becomes hard to read.

Matrix: many combinations from one recipe

The matrix feature lets you describe a set of axes, such as operating system and version, and Jenkins creates a parallel stage for every combination. It is like a multiplication table: three systems times two versions gives six stages, all from one short description. This avoids copying the same stage again and again.

Every stage ends with a result, and you can decide what happens for each kind of result.

After a stage finishes, it has one of a few results. Success means all steps worked. Failure means a step broke. Unstable means the work finished but something like a test failed. Aborted means a person or a time limit stopped it. Skipped means a condition said the stage should not run.

The post section lets you attach actions that run depending on these results. Common choices include the following.

You can place post actions in two places: inside a single stage, so they run right after that stage, or at the pipeline level, so they run when the whole pipeline ends. Cleanup and notifications usually belong at the pipeline level, while stage-level post actions suit things like publishing that stage’s own test reports.

One of the greatest gifts of stages is visibility. Jenkins draws them for you.

Jenkins can show a grid on the job page called the Stage View. Each column is a stage. Each row is one run of the pipeline. Boxes are coloured by result, and each shows how long that stage took. At a glance you can see that the Build stage takes two minutes, the Test stage takes twelve minutes, and that the last three runs failed at Deploy.

Newer views can show the pipeline as a graph, including parallel branches drawn side by side and a detailed log for each stage. Clicking on a failed stage takes you straight to its own log, so you do not have to search through the whole build output. This is where stages truly pay off: they shorten the time between “something is red” and “I know where to look”.

Restarting from a stage

For declarative pipelines, Jenkins allows you to restart a finished run from a chosen stage. If the Deploy stage failed because of a temporary network problem, you can restart from Deploy and skip the long Build and Test stages that already passed. This saves time and is only possible because the work is divided into named stages. Note that a restart begins with the same code and settings as the original run.

Naming stages well

Because stage names appear on screens, in messages, and in reports, good naming matters. Keep names short, clear, and consistent across projects. If every team calls its test phase “Unit Tests”, people can compare pipelines easily. Avoid putting changing details such as dates or numbers in stage names, because that makes history harder to compare.

While every project is different, most delivery pipelines contain a familiar set of stages.

flowchart LR
  C["Checkout"] --> B["Build"]
  B --> U["Unit Tests"]
  U --> Q["Quality and Security Scan"]
  Q --> I["Integration Tests"]
  I --> P["Package and Publish"]
  P --> S["Deploy to Staging"]
  S --> A{"Approval"}
  A -->|"approved"| R["Deploy to Production"]
  A -->|"rejected"| X["Stop and Notify"]
  U -->|"tests fail"| F["Fail and Alert Team"]

Notice how the cheap, fast checks come first and the expensive, risky ones come last. This idea is called fail fast in pipeline design: if something is going to break, let it break as early and as cheaply as possible.

Stages bring great benefits, but every design choice has a price. Knowing both sides helps you decide how many stages to use and how to shape them.

How many stages is right?

There is no magic number, but there is a helpful guide. Make a stage when the work has its own clear goal, its own possible failure, and something worth timing or controlling separately. Do not make a stage for every single command. A pipeline with forty tiny stages is as unreadable as one with none. A pipeline of about four to ten well-named stages is often a comfortable size.

Stages often touch secrets and live servers, so they deserve careful protection.

Keep secrets out of the file

Some stages need passwords, keys, or tokens, for example to publish a package or reach a server. Never type these into the Jenkinsfile. Jenkins has a credentials store that keeps secrets encrypted. A stage refers to a secret by a friendly name, and Jenkins hands the real value to the stage only while it runs, hiding it in the log output. Give the secret to the smallest possible piece of work, ideally only the one stage that truly needs it.

Protect the risky stages

The stage that deploys to production is the most valuable target. Combine several protections: run it only on trusted branches using a when condition, require a human approval, allow only a small group of people to approve, and run it on a dedicated agent that other jobs cannot use.

Do not trust unknown code

If your pipeline builds code from public pull requests, an outsider might try to change the Jenkinsfile to steal secrets. Good setups build such untrusted changes on throwaway agents with no access to secrets, and only run the sensitive stages for code that has been reviewed and merged.

Other helpful habits

• Least privilege. Give each stage only the access it needs.
• Keep the controller free of builds. Stages should run on agents, not on the brain of the system.
• Use the script sandbox. Pipeline scripts run in a restricted mode, and unusual actions need an administrator’s approval.
• Update regularly. Keep Jenkins and its plugins current to close known holes.

Because stages are named and timed, they are perfect for measuring how healthy your delivery process is.

Each stage has its own log section, so when something fails you read only the relevant part. Many teams also send stage timings and results to monitoring tools such as Prometheus and show them on Grafana dashboards. Build logs can be sent to a central search system so that engineers can look across thousands of runs. Like nurses watching a patient’s pulse and temperature, they can spot small changes before they turn into emergencies.

A pattern is a proven habit. An anti-pattern is a tempting shortcut that usually causes pain later.

Patterns that work

Anti-patterns to avoid

These habits separate a calm pipeline from a chaotic one.

Best practices

1. Give every stage a clear, consistent name that says what it does, such as Build, Unit Tests, or Deploy to Staging.
2. Give every stage one clear goal. If you cannot describe it in one short sentence, it may be two stages.
3. Order stages from cheap and fast to expensive and risky, so failures appear as early as possible.
4. Use time limits. A timeout on stages, especially those that wait or call outside systems, keeps stuck runs from hanging.
5. Use when conditions to skip stages that do not apply, such as publishing on feature branches.
6. Pick the agent per stage carefully, and use labels or containers so each stage gets the tools it needs.
7. Run independent stages in parallel, but make sure you have enough executors.
8. Clean up in post actions using the always condition, so temporary files never pile up.
9. Publish reports even on failure, because a failed run is when you need them most.
10. Keep secrets in the credentials store, and expose them only to the stage that needs them.
11. Keep the Jenkinsfile in the repository and review changes like any other code.
12. Reuse stage logic through shared libraries when many projects need the same thing.

Common mistakes

Stages appear in almost every real Jenkins pipeline. Here are common ways teams use them.

A typical growth story

A small team begins with one long list of commands in a single job. After a painful outage they cannot find the failing part, so they split the work into Build, Test, and Deploy stages. Next they add a quality scan and run tests in parallel to save time. Later they add an approval stage before Production and a time limit on every stage. Finally they move the common stages into a shared library so new projects start with a good pipeline from day one. At each step the change was small, and the team never had to start over.

You started in a bicycle factory and finished with a complete picture of how Jenkins organizes automated work into clear, named phases.