We begin with the simplest possible picture: what the directive is, where it sits, and what it does to a stage.

Jenkins is a tool that automates building, testing, and delivering software. You describe the work in a file called a Jenkinsfile. That file contains a pipeline, which is an ordered list of stages such as Build, Test, and Deploy. Each stage holds steps, the individual actions like running a command.

By default, a stage runs every time the pipeline reaches it. The when directive changes that. You place it inside a stage, and you describe one or more conditions. Before running the stage, Jenkins checks the conditions. If they are true, the stage runs. If they are not true, Jenkins skips the stage and moves on. In one sentence: the when directive is a gate placed at the door of a stage.

What you gain

To see why the directive matters, imagine a pipeline without it and follow what goes wrong.

The world before conditions

In the early days of Jenkins, a job was a long list of shell commands that ran top to bottom. If you wanted the same code to behave differently on different branches, you created separate jobs, one per branch, each with slightly different settings. Ten branches meant ten jobs. A change to the build process meant editing ten places, and someone always forgot one.

Jenkins Pipeline, which became a built-in part of Jenkins with version 2.0 in 2016, moved the job description into a text file stored next to the code. The Declarative syntax arrived shortly after and reached its first stable release in early 2017. It came with the when directive from the start, because teams practising continuous delivery immediately needed a clean way to say “only deploy from the main branch”.

The problems it solves

• Wasted time. A documentation typo does not need a two-hour integration test suite.
• Wasted money. Stages that start large cloud agents or containers cost real money every time they start.
• Unsafe actions. A deployment that should only leave the main branch might run from an experiment.
• Copy and paste drift. Separate Jenkinsfiles for separate cases slowly disagree with each other.
• Noise. A page full of unrelated stage results hides the one that actually failed.

A handful of Jenkins words appear in every condition. Learn them once here.

Environment variables again

Many conditions read environment variables, which are named values that Jenkins keeps about the run. For example, when Jenkins builds a branch in a multibranch job, it stores the branch name in a variable called BRANCH_NAME. Several conditions read this value behind the scenes. Because these variables exist only in certain job types, the same condition can behave differently in different kinds of job. Keep this in mind, because it explains the most common surprise in the whole topic.

Now we look at the shape of the block: where it goes, what it must contain, and how Jenkins reads it.

The shape

The word when is followed by curly braces. Inside the braces you list one or more conditions. Each condition is a small named test, such as branch followed by the branch name you care about. That is the whole structure.

The rules

What a skipped stage means for the rest

When a stage is skipped, everything inside it is skipped too: its steps, its own environment values, and its stage-level post actions. Later stages continue normally. This matters when a later stage depends on something the skipped stage was supposed to produce. If a Deploy stage expects a file made by a skipped Package stage, Deploy will fail for a reason that has nothing to do with Deploy. Keep related stages under matching conditions.

Jenkins ships with a set of ready-made conditions. Here is the whole menu, each explained in a sentence, before we study the important ones in depth.

Notice the three groups. The first group asks about where the code came from: branch, tag, pull request. The second group asks about what changed: commit message and changed files. The third group asks about the state of the run: variables, expressions, and what started the build. The last three conditions are logic tools that combine the others.

These are the most used conditions. They answer the question: “Where did this build come from?”

The branch condition

The branch condition compares the current branch name to a pattern you give it. If you give the plain word main, only the main branch matches. You can also use a glob pattern, which is a simple wildcard style. A pattern such as release-* matches release-1, release-2.0, and so on. By default, patterns are read as globs. You can also switch the comparison style to an exact match or to a regular expression when you need more precision.

The biggest surprise: only in multibranch jobs

The branch condition depends on the branch name that Jenkins records for the run. That name is only recorded for multibranch pipelines. In a plain pipeline job, the value is not there, so the condition does not match, and your Deploy stage will be skipped even on the branch you meant. If your when conditions seem to be ignored, check the job type first. This is the number one reason people believe the when directive is broken.

The pull request condition

To detect a pull request explicitly, use changeRequest. Used alone, it is true when the build is for a pull request. You can add filters so it is true only for certain pull requests, such as those aimed at a particular target branch, or those from a certain author, or with a matching title. This lets you run extra checks on pull requests that target the release branch, while leaving other pull requests on a quicker path.

The tag conditions

Release processes often start with a Git tag. The buildingTag condition is true when the build was started for a tag. The tag condition goes further and compares the tag name to a pattern, so a pattern like v* matches every version tag. Together they let you build a stage that publishes a release only when someone creates a proper release tag.

Sometimes the question is not “where” but “what”. These conditions look at what actually changed.

The changeset condition

The changeset condition is true when at least one changed file matches a pattern. This is a favourite in monorepos, which are single repositories holding many services. If only the billing service folder changed, there is no reason to rebuild and retest the shipping service. A stage for the shipping service can carry a changeset condition for its own folder, and Jenkins will skip it whenever nothing in that folder moved.

Points to know about changesets

• It looks at the changes Jenkins recorded for this build, which are the changes since the previous build. It is not a comparison of the entire repository.
• The very first build of a branch may have no recorded changes, so a stage guarded only by changeset can be skipped on the first run. Plan for that.
• Patterns are globs by default, and there are options to control case sensitivity and to choose other comparison styles.
• A shared file changes everything. If several services depend on a common library folder, include that folder in each service’s condition.
• Pull request and branch builds can differ in what they record as changed, so test your condition on both.

The changelog condition

The changelog condition looks at the commit messages in the change list. It matches a text pattern, so a team can agree that a message containing “[skip deploy]” means “do not deploy this one”. It is simple and it works, but it relies on human discipline, and someone must remember to type the magic words. Use it for convenience switches, not for anything that protects production.

When none of the ready-made source conditions fit, these flexible conditions let you test almost anything.

The environment condition

The environment condition checks whether a named environment variable equals a value. You give the variable name and the expected value. It is neat when a setting such as the deployment target is stored in a variable, and you want a stage to run only for one target.

The equals condition

The equals condition compares two values that you provide, an expected one and an actual one. It is the tidy way to test a build parameter. For example, a yes-or-no parameter asking “should we deploy?” can be compared to the value you expect.

The expression condition

The expression condition is the most powerful and the most dangerous. You write a small Groovy expression, and the stage runs when it gives true. You can test anything: a parameter, a variable, a calculation. Because it is free-form, it is also the easiest place to make a mistake.

The text-versus-truth trap

Environment variables are always text. Even if you set a variable to the word false, Jenkins stores the text “false”. In Groovy, any non-empty text counts as true when tested for truthiness. So an expression that simply asks whether the variable is set will say yes, and the stage will run even though the value says false. The safe habit is to compare the text to the exact word you expect, and never to test bare text for truth.

Build parameters behave differently. A parameter defined as a true-or-false type is a real boolean when read through the parameters object, and it can be tested directly. But the same parameter read through the environment becomes text again. Decide which way you read it, and stay consistent.

Real rules are rarely one question. This chapter shows how to combine tests, like Lego bricks, into exactly the rule you need.

flowchart TD
  A["Stage reached"] --> B{"Is the build for the main branch"}
  B -->|Yes| D{"Is the deploy flag on"}
  B -->|No| C{"Is the build for a version tag"}
  C -->|Yes| D
  C -->|No| S["Skip the stage"]
  D -->|Yes| R["Run the stage"]
  D -->|No| S
    

The picture shows the thinking. First ask where the build came from: the main branch, or a version tag. If either is true, move on to the flag. If the flag is also on, run. Any other path ends in a skip. In the Jenkinsfile, this is an allOf group that contains one anyOf group and one flag check.

A caution on evaluation order

Jenkins generally works through nested conditions in order and may stop early once the answer is known, just as you stop reading a list of requirements once one fails. Do not build conditions that depend on a side effect of an earlier one, and keep every condition free of surprises such as running commands or changing values. A condition should only ask a question. It should never do work.

A build can start for many reasons. The triggeredBy condition lets a stage react to why the build began.

Every Jenkins build records a cause: the reason it started. Common causes include a person pressing the build button, a timer firing on a schedule, a change detected in source control, or another job finishing upstream. The triggeredBy condition is true when the build’s cause matches the one you name. You may also give extra detail, such as a specific user.

This chapter lifts the lid on the directive. Knowing the order of events explains why an agent sometimes starts for a stage that then gets skipped.

The moment of decision

When Jenkins starts a run, the controller reads the Jenkinsfile and turns the Declarative syntax into an internal plan. As the run reaches each stage, the controller checks whether the stage has a when block. If it does, the controller works out the conditions using the information it holds about the run: the branch name, the change list, the environment variables, the parameters, and the build cause. The answer is yes or no. Yes means the stage runs. No means Jenkins marks it skipped and moves to the next one.

Most conditions are simple lookups against data the controller already holds, so they are fast. An expression condition runs a small piece of Groovy on the controller, and Jenkins normally runs that in a protected mode called the sandbox, which limits what it may call. This protection matters, and it is why some clever code you would happily run on your laptop is rejected in a pipeline until an administrator approves it.

The surprise: the agent may already be running

By default, if a stage names its own agent, Jenkins first gets that agent ready and only then evaluates the when block. That means a stage can start a machine, start a container, or allocate a cloud worker, and then discover that its condition is false and skip everything. For cheap agents this is unimportant. For expensive ones, such as large cloud machines or Kubernetes pods, it is real waste.

The fix is a small option inside the when block called beforeAgent. When you set it to true, Jenkins evaluates the conditions first and only starts the agent if the answer is yes.

sequenceDiagram
  participant Ctl as Jenkins Controller
  participant Cond as When Conditions
  participant Agt as Agent for the Stage
  Note over Ctl,Agt: Default behaviour
  Ctl->>Agt: Request the stage agent
  Agt-->>Ctl: Agent is ready
  Ctl->>Cond: Evaluate the conditions
  Cond-->>Ctl: False so skip the stage
  Note over Ctl,Agt: With beforeAgent set to true
  Ctl->>Cond: Evaluate the conditions first
  Cond-->>Ctl: False so skip the stage
  Ctl->>Ctl: Move on with no agent started
    

Three timing options

When more than one is set, Jenkins follows a fixed priority, with the options step first, the input step second, and the agent step third. Availability of some of these options depends on the Declarative Pipeline plugin version, so confirm what your server supports.

Nested and parallel stages

Stages can be nested inside other stages, and stages can run side by side in parallel groups. Each stage can carry its own when. If the outer stage is skipped, everything inside it is skipped without further questions. If the outer stage runs, each inner stage checks its own condition in turn. Matrix-style stages, which run the same work over combinations of values, can also carry a when. Check your Jenkins version for the exact places it is honoured.

Saved state

Jenkins saves the progress of a pipeline so it can resume after a restart. Conditions are evaluated as each stage is reached, using the data recorded for the run, so a restart in the middle of a run does not change the meaning of the conditions that have already been decided.

The when directive is not the only way to make a pipeline choose. Picking the right tool keeps your file clear.

An important distinction is between before and after. The when directive decides before a stage whether it should run. The post conditions decide after the work is done what to do next depending on the result. Both use similar-looking words, but they answer different questions.

Conditions are often used to guard deployments. That makes it important to know what they can and cannot protect.

A condition is a rule, not a lock

A when block that says “deploy only from the main branch” is a rule written in the Jenkinsfile. Anyone who can change the Jenkinsfile can change the rule. On a pull request from a contributor, the Jenkinsfile in that pull request may be the one that gets used, depending on how your job is configured. A malicious change could remove the condition and add a step that steals secrets. Therefore a when block must never be your only line of defence.

Expression conditions and the sandbox

The expression condition runs Groovy on the controller. Jenkins guards this with the sandbox and a script approval process. When a Jenkinsfile in a repository uses something the sandbox blocks, an administrator sees an approval request. Approve these only after reading exactly what the code does. Blindly approving a method can open a path for someone to run harmful code on your controller.

Do not let user input drive a condition unchecked

If a build parameter is free text and you feed it into a condition, someone could type a value that triggers a stage you did not intend. Prefer parameters with fixed choices, and compare them to known values.

When a stage runs that should not, or does not run that should, here is how to find out why without guessing.

What Jenkins shows you

• The stage view. Skipped stages are drawn in a faded style, so you can see at a glance which ones did not run.
• The console log. Jenkins writes a message that a stage was skipped due to its when conditional. This is your first clue.
• The Pipeline Syntax page. It lists the exact condition forms available on your server.
• Replay. Lets you edit and rerun the pipeline to test a changed condition without committing.

flowchart TD
  A["A stage ran or skipped unexpectedly"] --> B{"Is the job a multibranch pipeline"}
  B -->|No| C["Branch and pull request conditions cannot match so use another test"]
  B -->|Yes| D{"Did you print the values the condition reads"}
  D -->|No| E["Print the branch name and variables in an earlier stage"]
  D -->|Yes| F{"Is the value text compared as truth"}
  F -->|Yes| G["Compare to the exact word instead"]
  F -->|No| H{"Is it a first build or a pull request"}
  H -->|Yes| I["Check the changeset and the PR branch name"]
  H -->|No| J["Review nesting and the logic between allOf and anyOf"]
    

Common symptoms and causes

A helpful debugging habit

Add a small stage near the top, with no condition, that prints the branch name, the change identifier, the build cause, and the parameters. Run the pipeline once and read the values. Most puzzles solve themselves once you see the real values that the conditions receive. Remove this stage when you are done, and never print secrets in it.

Signals worth tracking over time

Count how often each guarded stage is skipped. A stage that is skipped one hundred percent of the time may have a condition that can never be true. A stage that never skips may have a condition that is too loose. Both are worth a look during regular pipeline reviews.

Patterns are habits that keep pipelines calm. Anti-patterns are habits that keep creating puzzles at two in the morning.

Patterns that help

Anti-patterns to avoid

Let us put everything together. We follow a single imaginary Jenkinsfile through five different events and see which stages run each time.

The imaginary pipeline

A small team runs an online shop. Their multibranch Jenkinsfile has six stages. Compile and Unit Tests have no condition, so they always run. Integration Tests carry a condition for the main branch, and also run when the build was started by the overnight timer. Security Deep Scan runs only for the overnight timer. Publish Package runs only when a version-style tag is built. Deploy to Staging runs on the main branch only, and has beforeAgent set so no cloud machine starts for other builds.

Reading the table like a story

Spotting a hidden problem

Notice that the version tag build skips Integration Tests. That means a tag could be published from a commit whose integration tests have never been run in that exact build. In this design the team relies on the fact that tags are created only from commits already tested on main. That is a reasonable choice, but it is a decision the team should make consciously, and write down. Tables like this one are excellent for uncovering such hidden assumptions.

The directive is small, but its effect on speed and cost can be large. This chapter explains why.

The cost of a build you did not need

Every stage that runs uses some resource: processor time, memory, network, and often money. A large organisation may run thousands of builds per day. If each build runs ten minutes of unnecessary work, that adds up to hundreds of hours of wasted machine time every day. Gating expensive stages so they run only when they matter is one of the cheapest ways to reduce that waste.

The numbers above are only an illustration to show the scale, since one thousand builds times ten minutes is ten thousand minutes, or about one hundred sixty-seven hours. Your own numbers will differ, but the shape of the problem is the same.

Where the savings come from

Scaling across many repositories

As an organisation grows from a handful of pipelines to hundreds, the rules for who runs what start to matter more than any single stage. Teams with many repositories often place their standard conditions inside a shared library, which is a central bundle of pipeline code that every project can use. Then a change such as “run the deep scan only at night” is made once and reaches every project. Without such sharing, each repository slowly develops its own slightly different rules.

Cost of the conditions themselves

Most conditions are nearly free because they read data Jenkins already has. The exception is a condition that does real work, for example an expression that calls a slow service or reads a large file. Since conditions are evaluated on the controller, a slow one delays the decision and can put extra load on the busiest machine in your system. Keep conditions quick and simple. If a decision needs real work, do that work in an earlier stage, store the answer, and let the condition read the stored answer.

A balanced view of the directive, and the habits that keep it working for you.

Best practices in one place

1. Prefer facts over habits. Use branch, tag, and changeset conditions before commit message conditions.
2. Use multibranch jobs when your rules depend on branches, tags, or pull requests.
3. Set beforeAgent to true on stages that have expensive agents.
4. Compare text to exact words. Never test bare text for truth.
5. Keep conditions free of side effects. They should only ask questions.
6. Keep related stages under matching conditions, so no stage waits for output that was skipped.
7. Name your decisions. A single clear value near the top beats many copies of a long rule.
8. Add an override. A boolean parameter lets a person force a stage when needed.
9. Watch skip rates. A stage that never runs, or always runs, deserves a review.
10. Protect deployment separately. Use scoped credentials, branch protection, and approvals in addition to conditions.

The mistakes seen most often

Here is how the when directive tends to appear in real delivery pipelines. These are illustrative patterns in general terms, not claims about the private setups of any particular company.

Jenkins is one of the most widely used automation servers, and large engineering organisations have publicly described running it at scale. What tends to be common is a habit of careful gating: quick checks for everyone, heavier work for trusted branches, and deliberate release steps. The patterns below show that habit in practice.