In a Jenkins declarative pipeline, what does a stage's when directive do, and what does beforeAgent true change?

## What when does `when` is a stage-level directive in declarative syntax — scripted has no equivalent and uses an ordinary Groovy `if`. It wraps one or more conditions that Jenkins evaluates at runtime for that stage: ```groovy stage('Deploy') { when { branch 'main' } steps { sh './deploy.sh' } } ``` When the conditions are false, the stage is **skipped**: its steps do not run, the build log records that it was skipped due to the when conditional, and the visualisation greys it out. Crucially, skipping is not failing. The build's overall result is unaffected, so a pipeline whose deploy stage is skipped on feature branches still ends SUCCESS. Candidates who expect UNSTABLE or a red build here have not used it. ## The built-in conditions The conditions worth knowing, all real directive names: - `branch 'main'` — matches the branch name, with wildcard and regex forms. Only meaningful in multibranch pipelines, where Jenkins knows the branch. - `tag` and `buildingTag()` — the build is for a tag, optionally matching a pattern. - `changeRequest()` — the build is for a change request (a pull or merge request), with optional attribute filters such as the target branch. - `changeset 'src/api/**'` — the files changed in this build match a pattern. `changelog` instead matches a regular expression against the commit messages. - `environment name: 'DEPLOY_TO', value: 'production'` — an environment variable has a specific value. `equals expected: 2, actual: currentBuild.number` compares two values generally. - `triggeredBy 'TimerTrigger'` — the build was started by a particular cause. - `expression { return params.RUN_TESTS }` — arbitrary Groovy returning a boolean; the general escape hatch. They compose with `allOf { }`, `anyOf { }` and `not { }`: ```groovy when { beforeAgent true allOf { branch 'main' not { changeRequest() } expression { params.DEPLOY == true } } } ``` ## The default evaluation point, and why it costs you This is the part interviewers push on. By default the `when` condition is evaluated **after** Jenkins has entered the stage's agent. If the stage declares `agent { kubernetes … }` or `agent { docker 'node:22' }`, that means a pod or container has already been provisioned, the workspace prepared and (usually) the repository checked out — all for a stage that is then skipped. On a pipeline with a dozen conditionally-skipped stages, each with its own agent, that is minutes of wasted capacity per build and real cloud cost. `beforeAgent true` fixes it: ```groovy stage('Deploy to prod') { agent { label 'deployer' } when { beforeAgent true branch 'main' } steps { sh './deploy.sh' } } ``` Now the condition is checked first and the agent is only acquired if the stage will actually run. The obvious constraint follows from the ordering: a condition evaluated before the agent exists cannot inspect anything on that agent — no reading a file from the workspace, no shelling out. It can only use information the controller already has: branch, tag, parameters, environment variables set at pipeline level, build causes. ## Its two siblings `beforeInput true` moves the evaluation ahead of the stage's `input` directive, so Jenkins does not prompt a human to approve a stage that the condition was going to skip. `beforeOptions true` moves it ahead of the stage's `options`, which matters when those options are expensive or have side effects. When more than one is set, the earliest applies first: options, then input, then agent. All three are booleans written inside the `when` block itself, not beside it. ## The scripted equivalent, and why it is not the same In scripted syntax you would write `if (env.BRANCH_NAME == 'main') { stage('Deploy') { … } }`. The behaviour looks similar, but the stage simply never exists rather than existing-and-skipped, so it does not appear greyed out in the visualisation and the stage list differs between builds. That is a concrete example of what the declarative schema buys: a static stage list that the UI and restart-from-stage can rely on. ## Practical guidance Prefer specific built-in conditions to `expression`: `branch 'main'` states intent and is cheap, whereas an expression is opaque Groovy that runs under the sandbox. Add `beforeAgent true` by default on any conditional stage with a heavyweight agent — there is rarely a reason not to, and forgetting it is the most common performance defect in otherwise correct Jenkinsfiles.