A plain-language first look before any details.

Jenkins is a free, open-source automation server that builds, tests and delivers software. Its work is written as a pipeline, a recipe stored in a text file called the Jenkinsfile. A pipeline is split into stages, such as Build, Test and Deploy, and each stage contains steps, the single actions Jenkins performs.

The input step is a step whose action is to wait for a person. When the pipeline reaches it, Jenkins freezes the run at that exact point, shows a message to the people allowed to answer, and does nothing else until someone responds. It comes from a plugin named Pipeline: Input Step, which is included in almost every Jenkins installation that uses pipelines.

What a person sees

On the page of the running build, Jenkins shows a paused notice with your message and two buttons. The Proceed button is green and can carry your own label, such as “Deploy to production.” The Abort button ends the run. If you asked for extra answers, form fields appear above the buttons.

Many organizations, especially those in finance, healthcare and government, must show that a person approved a change before customers saw it. Others simply want a safety net before a risky action such as a database change. In all of these cases the input step turns “somebody should look at this” from a hallway conversation into a recorded, enforced part of the pipeline.

The problem it solves and the two styles of delivery it supports.

The problem: fully automatic is not always wanted

Early automation aimed to remove people completely. Reality is more nuanced. Some changes are risky, some depend on business timing, and some need a legal or safety review. If the pipeline cannot pause, teams invent awkward workarounds: they split one pipeline into two jobs and remember to start the second by hand, they send emails and hope someone replies, or they leave the last step commented out and ask an engineer to uncomment it. All of these are easy to forget, impossible to audit, and slow.

Continuous delivery and continuous deployment

Two phrases matter here. Continuous delivery means every change is always kept in a state that could be released, but a human chooses the moment. Continuous deployment goes one step further: every change that passes the tests goes to customers automatically, with no human in the middle. The input step is the natural tool for continuous delivery. It marks the exact place where the machine hands over to a person.

A handful of small ideas that make the rest easy.

Controller, agent and executor

Jenkins has a main brain, the controller, which schedules work and serves the web pages. The machines that really run your commands are agents. Each agent has a limited number of executors, which are slots for running one job at a time. Think of executors as cooking stations in a kitchen: there are only so many, and while one cook occupies a station nobody else can use it.

Build result

Every run finishes with a result: success, unstable, failure or aborted. When a person presses Abort on an input prompt, the run ends as aborted, shown in gray.

Approver, or submitter

The person who answers the prompt is called the submitter in Jenkins. You can restrict who is allowed to answer by naming users or groups. If you say nothing, any signed-in user with permission to build the job may answer.

Parameters

A parameter is a named question with a typed answer, such as a piece of text, a yes-or-no box, or a choice from a list. The input step can ask for parameters and give the answers back to the pipeline.

Input ID

Each prompt has an id, a short unique label. Jenkins uses it to build web addresses for the Proceed and Abort actions. If you do not choose one, Jenkins generates it for you.

Which parts of a Jenkins setup take part when a run waits for a person.

The input step is not a separate service. It lives inside the pipeline engine. When it runs, the engine records “this run is waiting for input” and stops advancing that run. The run is saved on the controller’s disk, so it can survive a controller restart and resume waiting afterwards. Meanwhile the controller keeps serving other builds normally.

flowchart LR
    DEV["Developer pushes code"] --> SCM["Source Control Server"]
    SCM -->|"webhook"| CTRL["Jenkins Controller"]
    CTRL --> ENG["Pipeline Engine"]
    ENG --> ST1["Build and Test stages"]
    ST1 --> INP["Input Step: run pauses"]
    INP --> UI["Build page: Proceed or Abort"]
    INP -->|"link and message"| NOTI["Chat and Email Services"]
    NOTI --> APP["Approver"]
    APP -->|"clicks Proceed"| UI
    UI -->|"resume"| ENG
    ENG --> ST2["Deploy stage"]
    UI -->|"clicks Abort"| END["Run ends as aborted"]

Read the diagram from left to right. A developer pushes code, and a webhook, which is an automatic message from one system to another, wakes the controller. The pipeline engine runs the early stages, then reaches the input step. The run pauses. A link and message are sent through chat or email, an approver opens the build page, and clicks Proceed or Abort. Proceed tells the engine to resume and run the Deploy stage. Abort ends the run.

The same idea appears in two shapes in a Jenkinsfile.

The input step

The step form is placed among the other steps inside a stage. It runs when the pipeline reaches that line. It can return the answers given by the person, which you can keep in a variable and use in later steps. Because it is a normal step, you can place it anywhere, including inside conditions, loops or a timeout wrapper.

The input directive

The directive form is placed at stage level, next to the stage’s other structural settings, and belongs only to Declarative Pipeline. It pauses the stage before the stage’s steps begin. The answers are made available to the stage as environment variables named after each parameter. The directive form is tidy and readable, and it has an important advantage: it pauses before an agent is assigned, so no executor is held during the wait.

The order inside a stage

When the directive is used, a stage is prepared in a fixed order: options are applied first, then the input prompt appears, then the agent is allocated, and finally the stage’s when rule is checked unless you chose to check it earlier. This order is the reason a stage-level timeout defined in the options also limits how long the prompt may wait.

Six settings shape every prompt.

Writing a good message

The message is the most important option and the most often neglected. A message such as “Continue?” forces the approver to open logs to understand what they are approving. A good message is short but complete. It names the service, the version, the target environment and, if useful, the link to the test report. The approver should be able to decide in ten seconds without opening anything else.

How a human answer flows back into the pipeline.

An input prompt can ask for typed answers. The kinds of questions match those used for ordinary build parameters in Jenkins, so anyone who has seen a “Build with Parameters” page will feel at home.

What the step returns

The value that comes back depends on how many questions you asked.

• No parameters: nothing useful comes back. Success of the step simply means “the person clicked Proceed.”
• One parameter: the step returns that single answer directly, such as the chosen environment.
• Several parameters: the step returns a small lookup table, called a map, with one entry per parameter name.

Passing answers onward

In the step form, you keep the returned value and use it in later steps of the same pipeline. In the directive form, each answer becomes an environment variable available to all steps in that stage. If a later stage needs the value too, copy it into a variable defined earlier in the pipeline.

flowchart LR
    Q["Prompt with questions"] --> A1["String: version"]
    Q --> A2["Choice: environment"]
    Q --> A3["Boolean: run migration"]
    A1 --> M["Answers collected"]
    A2 --> M
    A3 --> M
    M --> S1["Deploy steps use version and environment"]
    M --> S2["Optional migration step runs if ticked"]

What Jenkins actually does, from reaching the prompt to resuming.

flowchart TD
    A["Pipeline reaches input"] --> B["Engine saves the run position"]
    B --> C["Run shows Paused for Input"]
    C --> D{"Who responds?"}
    D -->|"Allowed approver clicks Proceed"| E["Answers validated and stored"]
    D -->|"Approver clicks Abort"| F["Run ends as aborted"]
    D -->|"Nobody within the time limit"| G["Timeout stops the run as aborted"]
    D -->|"Unauthorized user tries"| H["Request is refused"]
    H --> C
    E --> I["Log shows: Approved by user"]
    I --> J["Engine resumes next steps"]

Notice that while the run waits, nothing is executing. The pipeline is simply a saved position and a web form. This is why a prompt can wait for hours or days without using processing power, provided you have not placed the wait on an agent, which the next chapter explains.

The single most important habit for using input well.

Remember executors, the work slots on agents. When a stage runs on an agent, it occupies one executor until the stage ends. If an input prompt is placed inside that stage, the executor stays occupied for the whole wait, even though nothing is running. If the approver takes until tomorrow morning, an expensive machine slot sits idle overnight.

flowchart LR
    subgraph BAD["Wasteful design"]
        B1["Agent allocated"] --> B2["Build and test"]
        B2 --> B3["Input waits while agent is held"]
        B3 --> B4["Deploy steps"]
    end
    subgraph GOOD["Efficient design"]
        G1["Agent allocated"] --> G2["Build and test"]
        G2 --> G3["Agent released"]
        G3 --> G4["Input waits with no agent"]
        G4 --> G5["Agent allocated again"]
        G5 --> G6["Deploy steps"]
    end

How to wait without an agent

• Declare no agent at the top of the pipeline and give each working stage its own agent. Place the approval in its own stage that has no agent.
• Use the directive form, which pauses before the agent for that stage is allocated.
• In scripted pipelines, place the input step outside the block that requests a machine.

What you give up

When the agent is released, the workspace on it may be cleaned or reused. If the deploy stage needs the files built earlier, save them first, either by stashing them, which is Jenkins’ way of temporarily storing files for later stages, or by archiving them. The next agent then retrieves them. This small extra work is the price of not wasting slots, and at scale it is well worth paying.

A prompt with no time limit is a trap for the future.

By default an input prompt waits indefinitely. That sounds polite but causes real trouble. Forgotten builds pile up in the list of running jobs. Their old artifacts and records cannot be cleaned up. Weeks later someone clicks Proceed on a build whose code is long out of date, and stale software reaches production.

Wrap the prompt in a timeout

Jenkins has a general-purpose timeout step. You wrap the input inside it and choose an amount of time and a unit, such as minutes, hours or days. If nobody answers before the time expires, Jenkins cancels the wait and the run ends as aborted. In the declarative directive form, a timeout placed in the stage’s options also covers the prompt, because options are applied before the prompt appears.

Timed out versus refused

Both a timeout and a person’s Abort end the run as aborted, so at first glance they look the same. They are very different in meaning: one means “nobody answered,” the other means “somebody said no.” Simple pipelines treat both alike. More advanced pipelines catch the interruption and check whether it came from the timer or from a person, then send a different message for each.

Both answers change the future of the run.

When the approver proceeds

The answers, if any, are stored, a line in the log records who approved, and the pipeline moves on to the next steps. In the build history the run continues as a normal run, and its final result depends on the remaining stages.

When the approver aborts

The run ends immediately with the aborted result. Later stages are skipped. This is not an error; it is a valid, intentional answer. The gray color tells your team that a person decided to stop, not that the code is broken.

Reacting with the post section

The post section, the block that runs when a pipeline or stage finishes, has a condition named aborted. It runs when the run ended as aborted, which includes both a refusal and a timeout. This is the ideal place to send a message such as “The release was not approved” or to release resources that earlier stages reserved. Pipelines that start temporary test environments before the prompt should always tear them down in aborted or cleanup, or those environments will keep running and costing money.

flowchart TD
    P["Input prompt"] --> R{"Answer"}
    R -->|"Proceed"| OK["Deploy stage runs"]
    R -->|"Abort"| AB["Run ends as aborted"]
    R -->|"Time expires"| TO["Run ends as aborted"]
    OK --> PS["Post: success or failure blocks"]
    AB --> PA["Post: aborted block"]
    TO --> PA
    PA --> CL["Post: cleanup block"]
    PS --> CL

A button is only as safe as the list of people who can press it.

If you do not set a submitter list, any user who has permission to build the job can answer the prompt. That may be far too many people. The submitter option narrows it to named users or groups. Groups are especially useful because people join and leave teams, and you do not want to edit the Jenkinsfile each time.

Separation of duties

In many companies a rule says that the person who wrote a change must not be the person who approves its release. The input step does not enforce this by itself. However, the submitterParameter option gives you the approver’s name as a variable. A pipeline can compare it with the name of the person who started or committed the build and stop the run if they are the same. This turns a policy document into automatic enforcement.

Where the identity comes from

Approver names come from whatever security system your Jenkins uses, such as Jenkins’ own user database or a company single sign-on service. The quality of your approval record therefore depends on the quality of your login setup. Shared accounts, where several people use the same login, make an approval record worthless because nobody can tell who really clicked.

Follow the answers and the approver’s name through the pipeline.

flowchart LR
    A["Approver fills form"] --> B["Answers: version, environment"]
    A --> C["Approver name"]
    B --> D["Deploy steps"]
    C --> E["Audit message in chat"]
    C --> F["Separation of duties check"]
    D --> G["Deployment record"]
    E --> G
    F -->|"same person"| H["Stop the run"]

The important principle is never trust a typed answer blindly. A person may mistype a version or pick the wrong option. Check the value against what the pipeline built. If the approver enters a version that does not match the build, stop and show a clear message instead of deploying something unexpected.

A prompt nobody knows about is just a delay.

Jenkins shows a paused notice on the build page, but approvers do not sit staring at build pages. A prompt that sits unseen for six hours is a common cause of slow releases. The fix is a notification sent just before the input step, telling the right people that a decision is waiting.

What a good notification contains

• The what: service name and version.
• The where: the target environment.
• The evidence: test results and a link to the report.
• The link: a direct address to the build page or the prompt.
• The deadline: when the prompt will time out.

Some teams also allow approval directly from chat with a button. That can be convenient, but it adds another system to secure, so treat it with the same care as the Jenkins page itself. Make sure the approval still passes through a verified identity.

What happens when new code keeps arriving while an approval is pending.

Real teams push code several times a day. Each push starts a build, and each build may reach the approval gate. Now imagine three builds all paused at the same prompt: version 4.10, 4.11 and 4.12. If the approver proceeds with 4.10 after 4.12 exists, an older version replaces or competes with newer work. This is a classic mistake in delivery pipelines.

Ways to keep order

Parallel branches

Jenkins can run several branches side by side in a stage. Putting an input prompt inside a parallel branch is possible but confusing, because the page then shows several waiting prompts and approvers may lose track. Prefer one prompt after the parallel work is done, asking for a single decision on the combined result.

Proven ways of arranging human gates.

Habits that seem fine at first and cause pain later.

A checklist to apply to any Jenkinsfile today.

Mistakes people make when they are new

Forgetting the files. After the wait, the deploy stage may run on a fresh agent with an empty workspace. If the built package was not saved with stash or archive, the stage fails looking for files that are gone.

Duplicating IDs. Two prompts in one run with the same id can confuse the approval links. Give each a unique, readable id.

Assuming Abort means broken. Aborted is not failed. Alerts that treat both alike will send false alarms whenever a person simply declines.

Ignoring restarts. A run waiting for input survives a controller restart, but the approver may not know that. After maintenance, check whether prompts are still pending and tell the approvers.

Skipping the practice run. Test the whole path on a test branch: proceed once, abort once, and let one time out. The first time these paths run should never be during a real release.

An honest look at what the input step does well and where it strains.

Trade-offs to weigh

There is no universally right answer. The correct trade-off depends on how risky your changes are, how large your team is and how quickly approvers respond. What matters is that you choose deliberately and write down why.

An approval gate is a security control, so it must be built like one.

The input step sits at the boundary between “code that passed tests” and “code that reaches customers.” That makes it a target. Anyone who can bypass or fake the approval can push unreviewed code to production. Good security around it is mostly common sense applied carefully.

Validate what was typed

Any text an approver types can end up inside a command. If a pipeline pastes a typed value straight into a command line, a careless or hostile entry could run something unintended. Use choices instead of free text where possible, and check any text against a strict pattern before use.

How to know that your approval gates are healthy and not slowing you down.

What Jenkins logs for you

When a person proceeds, the console log records that the input was approved and by whom. When someone aborts, the log records the abort and who did it. This gives you a basic audit trail with no extra work. Add your own log lines for the parameters chosen, so a later reader sees not just that a release was approved but which version and environment.

Metrics worth watching

Monitoring plugins that expose Jenkins numbers to systems such as Prometheus, plus dashboards on a wall screen, make waiting builds visible to everyone. Some teams add an alert when a prompt has been waiting longer than a chosen time, so that stuck approvals are noticed before the timeout ends them.

What waiting costs when hundreds of builds run each day.

A prompt placed correctly costs almost nothing in computing terms: the run is a saved position and a small web form. The cost is in time and attention, and in what the run holds while it waits.

Scaling practices

• Gate only what matters. Ten prompts a day for one approver is a recipe for careless clicks.
• Use milestones so only the newest build waits.
• Use groups so approvals do not depend on one person.
• Use notifications to shorten the time from prompt to answer.
• Save files smartly. Stash only what the next stage needs, not the entire workspace.

Those numbers are only an illustration, but the message is real. Trimming the average wait by a third, through better notifications and a wider approver group, gives back ten hours of pipeline time every day for a team that size.

How the ideas look in the kinds of organizations that run Jenkins at scale.

flowchart TD
    C["Code pushed"] --> B["Build and unit tests"]
    B --> SC["Security scan"]
    SC --> ST["Deploy to staging"]
    ST --> AT["Automated acceptance tests"]
    AT --> N["Notify approvers with link"]
    N --> G{"Input: approve production?"}
    G -->|"Proceed"| PR["Deploy to production"]
    G -->|"Abort or timeout"| TD["Tear down and notify team"]
    PR --> V["Post-deploy checks"]
    V --> DONE["Done and recorded"]

Where the input step fits among its alternatives.

The parameterized build is the closest relative. It asks its questions before the pipeline starts, so nothing waits and no run sits paused. Its weakness is that the person must decide before seeing the results of the tests. The input step asks after the machine has produced evidence, so the human decides with better information.

Follow one imaginary pipeline from push to production.

A small team owns a booking service. Their pipeline has four stages: Build, Test, Staging and Production. There is no agent at the top. The first three stages each use their own agent. The Production stage has an input directive that lets only the release-managers group proceed, with a four-hour time limit and a green button labeled “Release to customers.”

Had Ravi clicked Abort, or had four hours passed without an answer, the run would have ended as aborted. The post section’s aborted block would have torn down the staging environment and told the team the release was not approved. No manual cleanup, no forgotten machines, and a clean record either way.

Symptoms, likely causes and calm fixes.

A calm debugging routine

1. Open the build page and confirm the run really is paused for input.
2. Check who is trying to proceed and whether they are on the submitter list.
3. Look at the agent usage on the executor status page to see if a slot is held.
4. Read the log around the prompt for the approver line and any errors after resuming.
5. Reproduce on a test branch and change one thing at a time.

Every important word in this guide in one place.

Short answers to the questions that come up most often.

The whole story in a few lines.

The input step gives a Jenkins pipeline a human gate. It pauses the run, asks a question, waits for an authorized person, and then either continues or stops. It can collect typed answers, record who approved, and survive restarts. Used well, it sits outside any agent, has a time limit, names who may answer, tells them a decision is waiting, and cleans up whichever way the answer goes. Used badly, it wastes machines, piles up forgotten builds and creates approvals that mean nothing.