In a declarative Jenkinsfile, what is the difference between `agent any` at the top of the pipeline and `agent none`, and what must each stage do when the top-level directive is `agent none`?
answer
- one directive, two shorthands
- who holds the executor, and how long
- approval stages should not pin a machine
- none means every stage declares its own
- fresh workspace, fresh checkout per stage agent
basics
~20 sagent any lets Jenkins run the whole pipeline on any available executor, allocating one workspace for the entire run. agent none allocates no executor at pipeline level, so every stage must declare its own agent block.
solid answer
~50 sThe top-level `agent` directive in a declarative Jenkinsfile decides where the pipeline body runs. `agent any` tells Jenkins to pick any node with a free executor, allocate a workspace there, check out the SCM automatically, and hold that executor for the whole run — including the time spent waiting on an `input` step. `agent none` allocates nothing at the top level; it is the way you say "different stages run in different places". Under `agent none`, every `stage` must supply its own `agent` (for example `agent { label 'linux' }` or `agent { docker { image 'node:22' } }`), and a stage without one fails the pipeline. Each stage agent gets its own workspace and its own automatic `checkout scm`, so nothing carries over between them implicitly. Steps that need a workspace — `sh`, `readFile`, `archiveArtifacts` — cannot sit at pipeline level under `agent none`, including in a pipeline-level `post` block.
code
groovy · 22 linespipeline {
agent none
stages {
stage('Build') {
agent { label 'linux' }
steps {
sh 'make dist'
stash name: 'dist', includes: 'dist/**'
}
}
stage('Approve') {
steps { input message: 'Deploy to production?' }
}
stage('Deploy') {
agent { label 'deploy' }
steps {
unstash 'dist'
sh './deploy.sh dist'
}
}
}
}go deeper
Be able to say that the top-level agent directive is mandatory, that any runs the pipeline on any free executor with an automatic source checkout, and that none requires every stage to declare its own agent.
Explain the executor cost: with agent any the node stays reserved through waits and approvals, which is exactly the case agent none plus per-stage agents exists to solve. Mention the implicit checkout scm and skipDefaultCheckout().
Show you have debugged it: a pipeline-level post with no node, a deploy stage that cannot see build output because its workspace is fresh, and a fleet starved by pipelines parked on input while holding executors.
Frame it as capacity and blast radius. Decide a house convention for approval-bearing pipelines, cap how long an executor may be held, and be ready to justify per-stage agents against the extra scheduling latency and workspace churn they create.
## What the agent directive actually decides In declarative Jenkins pipelines the `agent` directive answers one question: on which machine, and in which workspace, does this block of the pipeline execute? Jenkins has a controller that orchestrates and a set of agents that execute; the `agent` directive is how a Jenkinsfile expresses which of those agents it wants. It is mandatory at the top level of a `pipeline { }` block — you must write something, even if that something is "nothing". ## agent any ```groovy pipeline { agent any stages { stage('Build') { steps { sh 'make' } } } } ``` `agent any` means: take any node that has a free executor and no restriction preventing this job from running there. Jenkins then does three things before the first stage runs. It reserves an executor, it creates (or reuses) a workspace directory on that node, and it performs an implicit `checkout scm` so the repository the Jenkinsfile came from is present. That implicit checkout is easy to forget, and you can turn it off with `options { skipDefaultCheckout() }`. The important consequence is duration. The executor is held for the *entire* pipeline, not just the parts doing work. If a stage sits on an `input` step waiting for a human to click Deploy, the executor and the workspace stay reserved the whole time. On a small fleet, a handful of pipelines parked on approvals can starve every other job. ## agent none ```groovy pipeline { agent none stages { stage('Build') { agent { label 'linux' } steps { sh 'make' } } stage('Approve'){ steps { input message: 'Ship it?' } } stage('Deploy') { agent { label 'deploy' } steps { sh './deploy.sh' } } } } ``` `agent none` allocates nothing at pipeline level. Each stage that needs to run commands declares its own agent, and stages that need no workspace — an `input` gate, a `milestone`, a notification built from `currentBuild` metadata — hold no executor at all. This is the standard shape for any pipeline with a human approval in the middle, and the standard shape for pipelines that build on one platform and deploy from another. The rules that follow from it are strict: - A stage with steps but no `agent` fails validation at run time. (`stage` blocks that only contain `parallel` or `stages` are the exception — the nested blocks carry the agents.) - Each stage agent gets a **fresh workspace** and its own implicit `checkout scm`. Build outputs from the previous stage are not there, because they were never in source control. Moving files between stages needs `stash`/`unstash` or an artifact repository. - Pipeline-level `post` blocks execute without a node. `post { always { sh 'cleanup.sh' } }` will fail under `agent none` because `sh` requires a workspace. Wrap it in a `node('label') { }` block, or put the `post` inside a stage that has an agent. ## Stage-level agents also work under a top-level agent A stage may declare its own `agent` even when the pipeline has one. Jenkins then allocates a second executor for that stage, on top of the one the pipeline already holds. That is occasionally what you want (a stage that must run on Windows in an otherwise Linux pipeline), but it doubles the executor cost, which is why `agent none` plus per-stage agents is the cleaner pattern when *every* stage has its own home. ## Other forms the directive takes `agent any` and `agent none` are the two built-in shorthands. The others name a target explicitly: `agent { label 'expr' }` for label routing, `agent { node { label 'x'; customWorkspace '/build/x' } }` when you need to control the workspace path, `agent { docker { image '...' } }` to run inside a container, `agent { dockerfile true }` to build that container from a Dockerfile in the repository, and `agent { kubernetes { ... } }` to get a pod per build. ## What interviewers are checking The short answer — "any means anywhere, none means nowhere" — is table stakes. What separates candidates is the follow-through: knowing that an executor is held across an `input`, knowing that each stage agent brings a fresh checkout and an empty workspace, and knowing that a pipeline-level `post` under `agent none` has no place to run a shell command.
- Why does a pipeline-level post block often fail under agent none, and how do you fix it?A pipeline-level `post` block runs outside any stage, so under `agent none` there is no node and no workspace. Steps like `sh`, `junit` or `archiveArtifacts` fail immediately. Either wrap the body in a `node('label') { ... }` block so it allocates its own executor, or move the `post` block inside a stage that already has an agent.
- What does options { skipDefaultCheckout() } change, and when would you want it?It suppresses the implicit `checkout scm` that Jenkins performs when it allocates an agent. You want it when a stage does not need the source at all — a deploy stage that only consumes a stashed artifact, for example — or when you need to control the checkout yourself with an explicit `checkout` step and custom refspec, depth or submodule options.
- If a pipeline already declares a top-level agent, what happens when a single stage declares its own?Jenkins allocates an additional executor and workspace for that stage while still holding the pipeline-level one. The stage runs on its own node, and its workspace is separate. It is legitimate for a one-off platform requirement, but paying for two executors for the length of a stage is why `agent none` with per-stage agents is preferred when most stages need distinct machines.
saying these in an interview costs you the question
- Thinking agent none makes the pipeline run on the controller
- Assuming stage workspaces are shared because it is one pipeline
- Believing an input step releases the executor under agent any
- Saying agent any picks the least loaded agent by CPU
- Forgetting that each stage agent re-runs checkout scm