A Jenkins pipeline stage waiting on a manual approval has held a build agent and its workspace for two days. Why is that happening, and how do you gate the deploy without pinning the executor?

## Two forms, one keyword Jenkins gives you `input` twice. As a **step**, it is called from inside `steps` like any other step. As a **directive**, it is a block on the stage itself, alongside `agent`, `options` and `when`. They read almost identically in a Jenkinsfile and they behave differently in exactly the way this incident exposes. ```groovy // Step form — pauses inside the stage body, on the agent stage('Deploy') { agent { label 'deploy' } steps { input message: 'Deploy to production?' sh './deploy.sh' } } ``` ```groovy // Directive form — pauses before the agent is entered stage('Deploy') { options { timeout(time: 8, unit: 'HOURS') } input { message 'Deploy to production?' ok 'Deploy' submitter 'release-managers' submitterParameter 'APPROVER' } agent { label 'deploy' } steps { sh "./deploy.sh --approved-by=${env.APPROVER}" } } ``` ## Why the step form holds an executor A Pipeline step inside a stage with an agent runs on that agent, in that agent's workspace, occupying one of the node's executors. `input` does not release any of that while it waits — from the node's point of view the build is simply still running. Two days of waiting is two days of one executor unavailable to every other job, plus a workspace directory nobody can reclaim. On a small fleet, three pending approvals can deadlock the queue: builds wait for executors that are held by builds waiting for humans. The directive form pauses the stage after its `options` are applied and before entering the stage's `agent`, so at approval time no heavy executor has been claimed at all. The run still consumes the pipeline's own lightweight executor on the controller — that is how it stays resumable — but that is cheap and is what Jenkins is designed to hold for long-lived runs. The same reasoning explains the companion pattern: declare `agent none` at the top of the pipeline and give each stage its own agent, so nothing is allocated across a gate that sits between stages. ## Always bound the wait An approval with no deadline is a build that lives forever, and forever is long enough for the artifact to be stale, the branch to have moved on, and the queue to fill with pending gates. Wrapping the stage in `options { timeout(time: 8, unit: 'HOURS') }` makes an unanswered approval expire. When it does, the run ends ABORTED — not UNSTABLE, and not auto-approved. Handle that in `post { aborted { ... } }` if you want a notification. Rejecting the input in the UI likewise aborts the run. ## Who may approve, and recording who did `submitter` restricts approval to named users or groups, which is what makes the gate an actual control rather than a formality — without it, anyone who can see the build can click. `submitterParameter` names a variable that receives the approving user's ID, so the deployment can log or pass on who authorised it. `parameters` inside the directive prompts for values at approval time (a version, a target region), and in the step form `input` returns those values so you can assign them. ## Ordering hazards Manual gates create a queue of approvable builds, and they can be approved out of order: build 40 sits pending, build 42 is approved and deploys, then somebody approves 40 and it deploys an older commit over the newer one. The `milestone` step is the guard — a build passing a milestone causes older builds that have not reached it to be aborted, so approvals cannot resurrect superseded runs. If the gate protects a single shared environment, consider also serialising the deploy so two approvals cannot deploy concurrently. ## What a complete answer covers Diagnose (the step form blocks on the agent), fix (directive form, or `agent none` with the gate between stages), bound (a stage `timeout`, and know that expiry aborts), and control (`submitter`, `submitterParameter`, and `milestone` for out-of-order approvals). Interviewers ask this one because it is the intersection of pipeline flow control and fleet capacity, and because almost every team has been bitten by it.