Declarative Pipeline in Depth

Every declarative Pipeline directive that matters, run on a real controller: environment, parameters, options, triggers, when, parallel, matrix, post, input, stash and script.

By The Dark DebuggerUpdated 34 min read

This article goes through the declarative Pipeline directives one at a time, each with a Jenkinsfile I ran and the log it produced, and finishes with a complete release pipeline that uses most of them together. It builds directly on Your First Pipeline, which introduced pipeline, agent, stages, steps and a first post block; read that first. Credentials appear here only briefly; Credentials and Secrets covers them properly.

Why the details matter

A first Jenkinsfile runs the tests. A pipeline you trust with releases has to answer harder questions. What happens if a step hangs for an hour? Should a docs-only change deploy? Can two deploys run at the same time? Who approves production, and does the build hold an agent hostage while it waits? How do you build for three platforms without three copies of the same stage? Declarative Pipeline has a directive for each of these, and each one has a gotcha I hit while testing.

Here is where each directive is allowed. "Top" means directly inside pipeline; "stage" means inside a stage:

DirectiveTopStagePurpose
agentyes (required)yesWhere the steps run
environmentyesyesEnvironment variables, including credentials
parametersyesnoInputs for Build with Parameters
optionsyesyes (subset)Timeouts, retries, log timestamps, concurrency
triggersyesnoCron, SCM polling, upstream jobs
toolsyesyesPut configured tool installations on the PATH
whennoyesRun the stage only if a condition holds
inputnoyesWait for a human before the stage
parallel, matrix, stagesnoyesRun nested stages concurrently, per axis, or in sequence
postyesyesSteps that run after, depending on the result

environment

environment sets variables for every sh step and for Groovy (as env.NAME). A stage-level block overrides the top-level one for that stage only, and credentials('id') binds a stored secret:

pipeline {
    agent any
    environment {
        APP_NAME    = 'logstats'
        DEPLOY_HOST = 'staging-01.internal.example.com'
        PACKAGE     = "${APP_NAME}-${BUILD_NUMBER}.tar.gz"
        API_TOKEN   = credentials('demo-api-token')
        DB          = credentials('demo-db')
    }
    stages {
        stage('Package') {
            environment {
                DEPLOY_HOST = 'staging-02.internal.example.com'
            }
            steps {
                sh 'echo "Packaging $PACKAGE for $DEPLOY_HOST"'
                echo "Groovy sees env.APP_NAME = ${env.APP_NAME}"
            }
        }
        stage('Secrets') {
            steps {
                sh 'echo "DEPLOY_HOST is back to $DEPLOY_HOST"'
                sh 'echo "token is $API_TOKEN (${#API_TOKEN} characters)"'
                sh 'echo "database user is $DB_USR"'
                sh "echo insecure: ${API_TOKEN}"
            }
        }
    }
}

demo-api-token is a "Secret text" credential and demo-db a "Username with password" credential that I created for this test. The run:

[Pipeline] withCredentials
Masking supported pattern matches of $API_TOKEN or $DB or $DB_USR or $DB_PSW
[…]
[Pipeline] { (Package)
[Pipeline] withEnv
[Pipeline] {
[Pipeline] sh
+ echo Packaging logstats-1.tar.gz for staging-02.internal.example.com
Packaging logstats-1.tar.gz for staging-02.internal.example.com
[Pipeline] echo
Groovy sees env.APP_NAME = logstats
[…]
[Pipeline] { (Secrets)
[Pipeline] sh
+ echo DEPLOY_HOST is back to staging-01.internal.example.com
DEPLOY_HOST is back to staging-01.internal.example.com
[Pipeline] sh
+ echo token is **** (21 characters)
token is **** (21 characters)
[Pipeline] sh
+ echo database user is ****
database user is ****
[Pipeline] sh
Warning: A secret was passed to "sh" using Groovy String interpolation, which is insecure.
		 Affected argument(s) used the following variable(s): [API_TOKEN]
		 See https://jenkins.io/redirect/groovy-string-interpolation for details.
+ echo insecure: ****
insecure: ****
[…]
Finished: SUCCESS

What to take from it:

  • Values can refer to earlier values (PACKAGE uses APP_NAME and BUILD_NUMBER). Use double quotes there, because Groovy builds the string.
  • The stage-level DEPLOY_HOST applied to Package only.
  • credentials() on a username/password credential creates three variables: DB (user:password), DB_USR and DB_PSW.
  • Jenkins masks secret values in the log as ****. Masking is a safety net, not a guarantee: a script that prints the secret base64-encoded, or one character per line, will leak it.
  • The last sh used double quotes, so Groovy put the secret into the command string before the shell saw it, and Jenkins warned about it. The value can then show up in places that aren't masked, such as the process list on the agent. Always reference secrets with single quotes ('$API_TOKEN') so the shell expands them.

parameters

parameters declares the inputs a build accepts. Inside the pipeline, read them as params.NAME. They are also exported as environment variables:

pipeline {
    agent any
    parameters {
        string(name: 'LOG_FILE', defaultValue: 'sample/access.log', description: 'Log to summarise')
        choice(name: 'TARGET_ENV', choices: ['staging', 'production'], description: 'Where to deploy')
        booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run the unit tests')
        password(name: 'SMOKE_PASSWORD', defaultValue: '', description: 'Password for the smoke-test account')
    }
    stages {
        stage('Show parameters') {
            steps {
                echo "params.TARGET_ENV=${params.TARGET_ENV}, params.RUN_TESTS=${params.RUN_TESTS}"
                sh 'echo "shell sees TARGET_ENV=$TARGET_ENV RUN_TESTS=$RUN_TESTS LOG_FILE=$LOG_FILE"'
                script {
                    if (params.RUN_TESTS) {
                        echo 'RUN_TESTS is a real boolean in Groovy'
                    }
                }
            }
        }
    }
}

The parameters only exist after Jenkins has run the Jenkinsfile once and registered them. Before that, the job isn't parameterized at all:

jcli build decl-params -s -v -p TARGET_ENV=production
 
ERROR: decl-params is not parameterized but the -p option was specified.

So the first build runs without parameters, and that first build has a nasty surprise. params.* returned the defaults, but the environment variables were empty:

jcli build decl-params -s -v
[…]
[Pipeline] echo
params.TARGET_ENV=staging, params.RUN_TESTS=true
[Pipeline] sh
+ echo shell sees TARGET_ENV= RUN_TESTS= LOG_FILE=
shell sees TARGET_ENV= RUN_TESTS= LOG_FILE=
[Pipeline] script
[Pipeline] {
[Pipeline] echo
RUN_TESTS is a real boolean in Groovy
[…]
Finished: SUCCESS

From the second build on, both views agree:

jcli build decl-params -s -v -p TARGET_ENV=production -p RUN_TESTS=false
[…]
[Pipeline] echo
params.TARGET_ENV=production, params.RUN_TESTS=false
[Pipeline] sh
+ echo shell sees TARGET_ENV=production RUN_TESTS=false LOG_FILE=sample/access.log
shell sees TARGET_ENV=production RUN_TESTS=false LOG_FILE=sample/access.log
[…]
Finished: SUCCESS

Two rules follow. Use params.NAME in Groovy, because it always has a value. And a step that matters (a deploy, a delete) must not depend on a parameter's environment variable during a job's first build. Note also that params.RUN_TESTS is a real boolean, so if (params.RUN_TESTS) works, while in the shell it is the string true or false. The password type hides the value in the UI, but a stored credential is still the better home for anything secret.

options

options changes how the pipeline or a stage runs. These are the ones I use in nearly every Jenkinsfile:

pipeline {
    agent any
    options {
        timeout(time: 10, unit: 'MINUTES')
        buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '5'))
        disableConcurrentBuilds()
        timestamps()
    }
    stages {
        stage('Prepare') {
            steps {
                sh 'rm -f attempts'
            }
        }
        stage('Download dependencies') {
            options {
                retry(3)
            }
            steps {
                sh '''
                    n=$(( $(cat attempts 2>/dev/null || echo 0) + 1 ))
                    echo $n > attempts
                    echo "download attempt $n"
                    [ "$n" -ge 3 ] || { echo "mirror timed out"; exit 1; }
                '''
            }
        }
        stage('Integration tests') {
            options {
                timeout(time: 5, unit: 'SECONDS')
            }
            steps {
                sh 'echo "waiting for the test database"; sleep 30'
            }
        }
    }
}

The download step fails twice and succeeds on the third attempt, simulating a flaky mirror. The integration-test step sleeps longer than its 5-second stage timeout:

[Pipeline] timeout
Timeout set to expire in 10 min
[Pipeline] {
[Pipeline] timestamps
[Pipeline] {
[…]
[Pipeline] { (Download dependencies)
[Pipeline] retry
[Pipeline] {
[Pipeline] sh
[…]
[2026-11-10T02:57:39.173Z] download attempt 1
[2026-11-10T02:57:39.173Z] + [ 1 -ge 3 ]
[2026-11-10T02:57:39.173Z] + echo mirror timed out
[2026-11-10T02:57:39.173Z] mirror timed out
[2026-11-10T02:57:39.173Z] + exit 1
[Pipeline] }
[2026-11-10T02:57:39.327Z] ERROR: script returned exit code 1
[2026-11-10T02:57:39.327Z] Retrying
[…]
[2026-11-10T02:57:40.239Z] download attempt 3
[2026-11-10T02:57:40.239Z] + [ 3 -ge 3 ]
[Pipeline] }
[Pipeline] // retry
[…]
[Pipeline] { (Integration tests)
[Pipeline] timeout
[2026-11-10T02:57:40.600Z] Timeout set to expire in 5 sec
[Pipeline] {
[Pipeline] sh
[2026-11-10T02:57:41.008Z] + echo waiting for the test database
[2026-11-10T02:57:41.008Z] waiting for the test database
[2026-11-10T02:57:41.008Z] + sleep 30
[2026-11-10T02:57:45.600Z] Cancelling nested steps due to timeout
[2026-11-10T02:57:45.604Z] Sending interrupt signal to process
[2026-11-10T02:57:46.218Z] Terminated
[…]
Timeout has been exceeded
org.jenkinsci.plugins.workflow.actions.ErrorAction$ErrorId: 9864c103-5bee-48de-afd5-bfa6d6b128ca
Finished: ABORTED
  • timeout at the top limits the whole run; on a stage, just that stage. When it fires, Jenkins interrupts the running process and the build ends ABORTED, not FAILURE. Every pipeline should have a top-level timeout: a hung build holds an executor forever otherwise.
  • retry(3) reruns the stage's steps up to 3 times in total. Files in the workspace survive between attempts (that's how the counter worked). Use retry for genuinely flaky external things like downloads, never to paper over flaky tests.
  • timestamps() prefixes each output line with a UTC timestamp (Timestamper plugin), which is how you find out where a slow build spends its time.
  • buildDiscarder(logRotator(...)) is the Pipeline form of Discard old builds. The values are strings: numToKeepStr: '20'.
  • disableConcurrentBuilds() queues a second build until the first finishes. I started two builds of a job whose only step is sh 'echo "deploying build $BUILD_NUMBER"; sleep 15', four seconds apart, asked the queue why the second was waiting, and later listed both builds (start times in UTC):
jcli build decl-concurrent; sleep 4
jcli build decl-concurrent; sleep 4
curl -g -sS -u "admin:$JENKINS_API_TOKEN" "http://localhost:8090/queue/api/json?tree=items[task[name],why]" \
  | jq -c '[.items[] | select(.task.name=="decl-concurrent") | {job: .task.name, why}]'
curl -g -sS -u "admin:$JENKINS_API_TOKEN" "http://localhost:8090/job/decl-concurrent/api/json?tree=builds[number,result,timestamp,duration]" \
  | jq -r '.builds[] | "#\(.number) \(.result) start=\(.timestamp/1000|floor|strftime("%H:%M:%S")) dur=\(.duration/1000|floor)s"'
[{"job":"decl-concurrent","why":"Build #1 is already in progress (ETA: N/A)"}]
#2 SUCCESS start=02:58:06 dur=16s
#1 SUCCESS start=02:57:51 dur=14s

Build #2 started only after #1 ended. Use it on anything that deploys or changes shared state: two deploys racing each other are worse than one waiting.

triggers

triggers accepts the same schedules as freestyle jobs (see Freestyle Jobs for the H syntax):

pipeline {
    agent any
    triggers {
        cron('H 2 * * 1-5')
        pollSCM('H/15 * * * *')
        upstream(upstreamProjects: 'logstats', threshold: hudson.model.Result.SUCCESS)
    }
    stages {
        stage('Nightly report') {
            steps {
                echo "Triggered by: ${currentBuild.getBuildCauses()*.shortDescription}"
            }
        }
    }
}

The same chicken-and-egg rule as for parameters applies: Jenkins learns about the triggers by running the Jenkinsfile. The job I created had no triggers; after its first build, the job configuration contained all three:

jcli get-job decl-triggers
[…]
    <org.jenkinsci.plugins.workflow.job.properties.PipelineTriggersJobProperty>
      <triggers>
        <hudson.triggers.SCMTrigger>
          <spec>H/15 * * * *</spec>
          <ignorePostCommitHooks>false</ignorePostCommitHooks>
        </hudson.triggers.SCMTrigger>
        <hudson.triggers.TimerTrigger>
          <spec>H 2 * * 1-5</spec>
        </hudson.triggers.TimerTrigger>
        <jenkins.triggers.ReverseBuildTrigger>
          <spec></spec>
          <upstreamProjects>logstats</upstreamProjects>
          <threshold>
            <name>SUCCESS</name>
            <ordinal>0</ordinal>
            <color>BLUE</color>
            <completeBuild>true</completeBuild>
          </threshold>
        </jenkins.triggers.ReverseBuildTrigger>
      </triggers>
    </org.jenkinsci.plugins.workflow.job.properties.PipelineTriggersJobProperty>
[…]

The build itself printed Triggered by: [Started from command line by admin]. The flip side: removing a trigger from the Jenkinsfile removes it from the job only after the next build. For branch and pull-request builds, use webhooks with multibranch pipelines rather than pollSCM.

tools

tools puts a tool installation that an administrator configured under Manage Jenkins → Tools on the PATH. The lab controller has only the default Git installation configured, which is enough to see the mechanism:

pipeline {
    agent any
    tools {
        git 'Default'
    }
    stages {
        stage('Versions') {
            steps {
                sh 'git --version'
            }
        }
    }
}
[Pipeline] { (Declarative: Tool Install)
[Pipeline] tool
[Pipeline] envVarsForTool
[Pipeline] }
[…]
[Pipeline] sh
+ git --version
git version 2.43.0
[…]
Finished: SUCCESS

Ask for a tool that isn't configured and the build fails before any stage runs. The linter catches it too, because it validates tool names against the controller:

    tools {
        jdk 'temurin-21'
    }
[…]
org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
WorkflowScript: 4: Tool type "jdk" does not have an install of "temurin-21" configured - did you mean "null"? @ line 4, column 13.
           jdk 'temurin-21'
               ^
 
1 error
 
Finished: FAILURE

did you mean "null"? is Jenkins' way of saying there are no JDK installations at all. Nowadays I prefer agents that already have the right tool versions installed (or container agents) over tools, but you will meet tools { maven 'maven-3.9' } in many existing Jenkinsfiles.

when

when decides whether a stage runs. Skipped stages show up as skipped in the log and stage view, which is far clearer than an if buried inside a shell step:

pipeline {
    agent any
    parameters {
        choice(name: 'TARGET_ENV', choices: ['staging', 'production'], description: 'Where to deploy')
        booleanParam(name: 'LOAD_TEST', defaultValue: false, description: 'Run the load test on a perf agent')
    }
    environment {
        DEPLOY_WINDOW = 'open'
    }
    stages {
        stage('Checkout') {
            steps {
                git url: 'file:///home/sid/logstats', branch: 'main'
            }
        }
        stage('Publish docs') {
            when { branch 'main' }
            steps { echo 'publishing docs from main' }
        }
        stage('Refresh sample report') {
            when { changeset 'sample/**' }
            steps { sh 'python3 logstats.py sample/access.log' }
        }
        stage('Deploy to production') {
            when {
                allOf {
                    expression { params.TARGET_ENV == 'production' }
                    environment name: 'DEPLOY_WINDOW', value: 'open'
                }
            }
            steps { echo "deploying to ${params.TARGET_ENV}" }
        }
        stage('Load test') {
            agent { label 'perf' }
            when {
                beforeAgent true
                expression { params.LOAD_TEST }
            }
            steps { echo 'running the load test' }
        }
    }
}

The first build, with defaults:

[Pipeline] { (Publish docs)
Stage "Publish docs" skipped due to when conditional
[…]
[Pipeline] { (Refresh sample report)
[Pipeline] echo
Warning, empty changelog. Probably because this is the first build.
Stage "Refresh sample report" skipped due to when conditional
[…]
[Pipeline] { (Deploy to production)
Stage "Deploy to production" skipped due to when conditional
[…]
[Pipeline] { (Load test)
Stage "Load test" skipped due to when conditional
[…]
Finished: SUCCESS

Then I committed a change under sample/ and built again with TARGET_ENV=production:

[Pipeline] { (Publish docs)
Stage "Publish docs" skipped due to when conditional
[…]
[Pipeline] { (Refresh sample report)
[Pipeline] sh
+ python3 logstats.py sample/access.log
requests: 12  unparsed: 1
by class: 2xx=7  3xx=1  4xx=1  5xx=3
5xx rate: 25.0%
[…]
[Pipeline] { (Deploy to production)
[Pipeline] echo
deploying to production
[…]
[Pipeline] { (Load test)
Stage "Load test" skipped due to when conditional
[…]
Finished: SUCCESS

Look at Publish docs: skipped both times, although the job builds main. branch only works in multibranch pipelines, where Jenkins sets BRANCH_NAME. In an ordinary Pipeline job, BRANCH_NAME is unset and the condition is silently false. That one cost me a few minutes of confusion; Multibranch Pipelines and Webhooks is where branch belongs. The changeset condition compares against the previous build of the job, so it is always false on a first build, as the warning says.

The Load test stage shows why beforeAgent true matters. Normally Jenkins allocates the stage's agent first and evaluates when afterwards. With beforeAgent true the condition goes first, so a skipped stage never asks for an agent. I removed that one line and ran the job again:

[Pipeline] { (Load test)
[Pipeline] node
Still waiting to schedule task
There are no nodes with the label ‘perf’

The queue confirmed "why":"There are no nodes with the label ‘perf’", and the build sat there, for a stage it was going to skip, until I stopped it (it ended ABORTED). On a busy controller the same thing means waiting minutes for an expensive agent just to be told "skipped". beforeInput and beforeOptions work the same way for input and options.

The conditions you will use most:

ConditionTrue when
branch 'main'Multibranch only: the branch being built matches (wildcards allowed)
changeset 'sample/**'A file matching the pattern changed since the previous build
environment name: 'X', value: 'y'An environment variable has that value
expression { ... }The Groovy expression is true (params.X == 'y', currentBuild.previousBuild == null)
tag 'v*', buildingTag()Building a tag (multibranch)
changeRequest()Building a pull request (multibranch)
triggeredBy 'TimerTrigger'The build was started by that cause
allOf, anyOf, notCombine the above

parallel

A stage can contain parallel stages. Under a single agent any, the branches run concurrently in the same workspace:

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git url: 'file:///home/sid/logstats', branch: 'main'
            }
        }
        stage('Checks') {
            failFast true
            parallel {
                stage('Unit tests') {
                    steps {
                        sh 'python3 tests/junit_runner.py reports/junit.xml 2>&1 | tail -1'
                    }
                }
                stage('Syntax') {
                    steps {
                        sh 'python3 -m py_compile logstats.py tests/*.py && echo "syntax ok"'
                    }
                }
                stage('Sample report') {
                    steps {
                        sh 'sleep 2; python3 logstats.py sample/access.log | head -3'
                    }
                }
            }
        }
    }
}
[Pipeline] { (Checks)
[Pipeline] parallel
[Pipeline] { (Branch: Unit tests)
[Pipeline] { (Branch: Syntax)
[Pipeline] { (Branch: Sample report)
[Pipeline] stage
[Pipeline] { (Unit tests)
[Pipeline] stage
[Pipeline] { (Syntax)
[Pipeline] stage
[Pipeline] { (Sample report)
[Pipeline] sh
[Pipeline] sh
[Pipeline] sh
+ python3 tests/junit_runner.py reports/junit.xml
+ tail -1
OK
[Pipeline] }
+ python3 -m py_compile logstats.py tests/junit_runner.py tests/test_logstats.py
+ echo syntax ok
syntax ok
[Pipeline] // stage
+ sleep 2
[…]
+ python3 logstats.py sample/access.log
+ head -3
requests: 11  unparsed: 1
by class: 2xx=6  3xx=1  4xx=1  5xx=3
5xx rate: 27.3%
[…]
Finished: SUCCESS

The interleaved output is normal; the stage view separates the branches cleanly. Because the branches share one workspace, they must not write the same files. (Here only one branch writes reports/.) If they need isolation, give each branch its own agent, which also spreads them over several machines.

failFast true stops the remaining branches as soon as one fails, instead of letting a 40-second test suite finish for a build that is already red:

[Pipeline] { (Branch: Lint)
[Pipeline] { (Branch: Slow integration tests)
[…]
+ echo logstats.py:12: line too long (131 > 100)
logstats.py:12: line too long (131 > 100)
+ exit 1
+ echo starting 40 s of integration tests
starting 40 s of integration tests
+ sleep 40
[…]
Failed in branch Lint
Sending interrupt signal to process
Terminated
[…]
Failed in branch Slow integration tests
[…]
ERROR: script returned exit code 1
Finished: FAILURE

matrix

matrix runs the same stages once per combination of axis values, as parallel branches, with each axis available as an environment variable. excludes removes combinations that make no sense:

pipeline {
    agent any
    stages {
        stage('Package') {
            matrix {
                axes {
                    axis {
                        name 'TARGET_OS'
                        values 'linux', 'darwin', 'windows'
                    }
                    axis {
                        name 'ARCH'
                        values 'amd64', 'arm64'
                    }
                }
                excludes {
                    exclude {
                        axis {
                            name 'TARGET_OS'
                            values 'windows'
                        }
                        axis {
                            name 'ARCH'
                            values 'arm64'
                        }
                    }
                }
                stages {
                    stage('Build') {
                        steps {
                            sh 'echo "packaging logstats for $TARGET_OS/$ARCH"'
                        }
                    }
                }
            }
        }
    }
}

Three operating systems times two architectures, minus one exclusion, gives five cells:

[Pipeline] { (Package)
[Pipeline] parallel
[Pipeline] { (Branch: Matrix - TARGET_OS = 'linux', ARCH = 'amd64')
[Pipeline] { (Branch: Matrix - TARGET_OS = 'darwin', ARCH = 'amd64')
[Pipeline] { (Branch: Matrix - TARGET_OS = 'windows', ARCH = 'amd64')
[Pipeline] { (Branch: Matrix - TARGET_OS = 'linux', ARCH = 'arm64')
[Pipeline] { (Branch: Matrix - TARGET_OS = 'darwin', ARCH = 'arm64')
[…]
+ echo packaging logstats for linux/amd64
packaging logstats for linux/amd64
+ echo packaging logstats for darwin/amd64
packaging logstats for darwin/amd64
[Pipeline] }
+ echo packaging logstats for windows/amd64
packaging logstats for windows/amd64
[Pipeline] // stage
+ echo packaging logstats for linux/arm64
packaging logstats for linux/arm64
[Pipeline] }
[Pipeline] }
+ echo packaging logstats for darwin/arm64
packaging logstats for darwin/arm64
[…]
Finished: SUCCESS

In real use, a matrix usually puts an agent { label "${TARGET_OS}" } inside it so each cell runs on a matching machine. Typical axes are platform × architecture, or language version × database version.

post conditions

post blocks run after the stages (or after a stage, at stage level), depending on the result. To see exactly which ones fire, I gave every condition an echo and drove the result with a parameter:

pipeline {
    agent any
    parameters {
        choice(name: 'OUTCOME', choices: ['success', 'unstable', 'failure'], description: 'Result to simulate')
    }
    stages {
        stage('Test') {
            steps {
                script {
                    if (params.OUTCOME == 'failure') {
                        error('test runner crashed')
                    }
                    if (params.OUTCOME == 'unstable') {
                        unstable('2 of 41 tests failed')
                    }
                }
                echo 'test stage finished'
            }
        }
    }
    post {
        always     { echo 'post: always' }
        success    { echo 'post: success' }
        unstable   { echo 'post: unstable' }
        failure    { echo 'post: failure' }
        changed    { echo 'post: changed' }
        fixed      { echo 'post: fixed' }
        regression { echo 'post: regression' }
        aborted    { echo 'post: aborted' }
        cleanup    { echo 'post: cleanup' }
    }
}

Six builds in a row, filtering the log down to the post: lines:

BuildResult (previous)post blocks that ran, in order
#1SUCCESS (none)always, changed, success, cleanup
#2FAILURE (SUCCESS)always, changed, regression, failure, cleanup
#3SUCCESS (FAILURE)always, changed, fixed, success, cleanup
#4UNSTABLE (SUCCESS)always, changed, regression, unstable, cleanup
#5UNSTABLE (UNSTABLE)always, unstable, cleanup
#6SUCCESS (UNSTABLE)always, changed, fixed, success, cleanup

The raw output of build #2, for example:

Started decl-post #2
post: always
post: changed
post: regression
post: failure
post: cleanup
ERROR: test runner crashed
Finished: FAILURE

What the table teaches:

  • The order is fixed: always, changed, fixed/regression, the result-specific block, cleanup last. It does not follow the order you write them in.
  • changed fires when the result differs from the previous build, and on the very first build.
  • fixed means "previous build was failed or unstable, this one succeeded"; regression means "this one is worse than the previous". These are the right hooks for notifications: tell people when something breaks and when it recovers, not on every green build.
  • cleanup always runs, after everything else, which makes it the place for cleanWs().
  • error('...') fails the build; unstable('...') marks it UNSTABLE and carries on with the stage.

input

input pauses the build until a person approves it. In declarative it belongs at stage level, together with a timeout so an unanswered request doesn't wait forever:

pipeline {
    agent none
    stages {
        stage('Build') {
            agent any
            steps {
                sh 'echo "packaged logstats-$BUILD_NUMBER.tar.gz"'
            }
        }
        stage('Deploy to production') {
            options {
                timeout(time: 30, unit: 'SECONDS')
            }
            input {
                message 'Deploy this build to production?'
                ok 'Deploy'
                submitter 'admin'
                parameters {
                    string(name: 'CHANGE_TICKET', defaultValue: '', description: 'Approved change ticket')
                }
            }
            agent any
            steps {
                sh 'echo "deploying build $BUILD_NUMBER under change $CHANGE_TICKET"'
            }
        }
    }
}

In the UI, the waiting build's console shows the request (for an input with parameters, an Input requested link that opens a form with the field and the Deploy and Abort buttons), and the stage view offers the same choice. submitter limits who may approve (user IDs or group names, comma-separated). I let the first build time out:

[Pipeline] { (Deploy to production)
[Pipeline] timeout
Timeout set to expire in 30 sec
[Pipeline] {
[Pipeline] input
Input requested
Cancelling nested steps due to timeout
[…]
Timeout has been exceeded
org.jenkinsci.plugins.workflow.actions.ErrorAction$ErrorId: cde55792-a1ec-4533-b45b-4360bf9cb5bf
Finished: ABORTED

For the second build I approved through the REST API, which is also how chat-ops bots do it. The pending request describes itself:

curl -sS -u "admin:$JENKINS_API_TOKEN" http://localhost:8090/job/decl-input/lastBuild/wfapi/pendingInputActions | jq .
[
  {
    "id": "76c8fde0a7ff8d38399b97319fc1eb81",
    "proceedText": "Deploy",
    "message": "Deploy this build to production?",
    "inputs": [
      {
        "type": "StringParameterDefinition",
        "name": "CHANGE_TICKET",
        "description": "Approved change ticket",
        "definition": {
          "defaultVal": null
        }
      }
    ],
    "proceedUrl": "/job/decl-input/lastBuild/wfapi/inputSubmit?inputId=76c8fde0a7ff8d38399b97319fc1eb81",
    "abortUrl": "/job/decl-input/lastBuild/input/76c8fde0a7ff8d38399b97319fc1eb81/abort",
    "redirectApprovalUrl": "/job/decl-input/lastBuild/input/"
  }
]
curl -sS -o /dev/null -w '%{http_code}\n' -X POST -u "admin:$JENKINS_API_TOKEN" \
  --data-urlencode 'json={"parameter":[{"name":"CHANGE_TICKET","value":"CHG-20417"}]}' \
  "http://localhost:8090/job/decl-input/2/wfapi/inputSubmit?inputId=76c8fde0a7ff8d38399b97319fc1eb81"
200
[Pipeline] input
Input requested
Approved by admin
[Pipeline] withEnv
[Pipeline] {
[Pipeline] node
Running on Jenkins in /home/sid/.jenkins/workspace/decl-input
[Pipeline] {
[Pipeline] sh
+ echo deploying build 2 under change CHG-20417
deploying build 2 under change CHG-20417

The input parameter became an environment variable ($CHANGE_TICKET), and the approver's name is recorded in the build.

Why agent none at the top and agent any per stage? Because an input step inside steps waits while holding the executor the stage was given. I compared the two forms (they are in Exercise 4), listing what each executor was running while the build waited for approval:

curl -g -sS -u "admin:$JENKINS_API_TOKEN" "http://localhost:8090/computer/api/json?tree=computer[displayName,executors[currentExecutable[url]]]" \
  | jq -c '[.computer[] | {node: .displayName, busy: [.executors[] | .currentExecutable.url // "idle"]}]'

With agent any at the top and input as a step:

[{"node":"Built-In Node","busy":["idle","http://localhost:8090/job/decl-step-input/1/"]}]

With agent none at the top and input at stage level:

[{"node":"Built-In Node","busy":["idle","idle"]}]

With the step-level input, one of the controller's two executors was tied up doing nothing until someone clicked. A release that waits overnight for approval would block half the builds on that agent. With a stage-level input and no top-level agent, the build waits without an executor and only takes one once approved.

stash and unstash

When stages run on different agents (or a workspace is wiped in between), stash saves files on the controller under a name and unstash restores them anywhere later in the same build:

pipeline {
    agent none
    stages {
        stage('Build') {
            agent { label 'built-in' }
            steps {
                git url: 'file:///home/sid/logstats', branch: 'main'
                sh 'mkdir -p dist && tar czf dist/logstats-$BUILD_NUMBER.tar.gz logstats.py'
                stash name: 'package', includes: 'dist/*.tar.gz'
            }
        }
        stage('Verify package') {
            agent { label 'built-in' }
            steps {
                deleteDir()
                unstash 'package'
                sh 'ls -l dist && tar tzf dist/logstats-$BUILD_NUMBER.tar.gz'
            }
        }
    }
}
[Pipeline] sh
+ mkdir -p dist
+ tar czf dist/logstats-1.tar.gz logstats.py
[Pipeline] stash
Stashed 1 file(s)
[…]
[Pipeline] { (Verify package)
[Pipeline] node
Running on Jenkins in /home/sid/.jenkins/workspace/decl-stash
[Pipeline] {
[Pipeline] deleteDir
[Pipeline] unstash
[Pipeline] sh
+ ls -l dist
total 4
-rw-r--r-- 1 sid sid 958 Nov  9 21:58 logstats-1.tar.gz
+ tar tzf dist/logstats-1.tar.gz
logstats.py
[…]
Finished: SUCCESS

The lab has only one node, so I used deleteDir() to prove the file really came back from the stash and not from a leftover workspace. Stashes are for small files within one build: they pass through the controller and are deleted when the build ends. Large files or anything you want to keep belong in archiveArtifacts or an artifact repository.

script blocks

script { } drops into scripted Pipeline (plain Groovy) inside a declarative stage: variables, if, loops, and step return values. Here it parses the tool's output and enforces an error budget:

stage('Error budget') {
    steps {
        script {
            def summary = sh(script: 'python3 logstats.py sample/access.log', returnStdout: true).trim()
            def rateLine = summary.readLines().find { it.startsWith('5xx rate:') }
            def rate = rateLine.split(':')[1].replace('%', '').trim().toDouble()
            echo "5xx rate is ${rate}%"
            if (rate > 5) {
                unstable("5xx rate ${rate}% is over the 5% error budget")
            }
            for (host in ['web-01', 'web-02', 'web-03']) {
                echo "would warn the on-call channel for ${host}"
            }
        }
    }
}
[Pipeline] { (Error budget)
[Pipeline] script
[Pipeline] {
[Pipeline] sh
+ python3 logstats.py sample/access.log
[Pipeline] echo
5xx rate is 25.0%
[Pipeline] unstable
WARNING: 5xx rate 25.0% is over the 5% error budget
[Pipeline] echo
would warn the on-call channel for web-01
[Pipeline] echo
would warn the on-call channel for web-02
[Pipeline] echo
would warn the on-call channel for web-03
[…]
Finished: UNSTABLE

It took me four attempts to get that block working, and every failure was instructive. The first two were rejected by the script security sandbox, which only allows Groovy methods on an approved list. The third ran but printed 5xx rate is 525.0%, because my parsing regex (replaceAll(/[^0-9.]/, '')) kept the "5" from "5xx". My rule after that: a script block of more than a few lines is a sign the logic belongs in a script in the repository (python3 ci/check_budget.py), where you can test it locally, or in a shared library.

agent variations

So far every example used agent any, agent none or agent { label '...' }. You will also see container agents:

pipeline {
    agent {
        docker { image 'python:3.12-slim' }
    }
    stages {
        stage('Test') {
            steps {
                sh 'python3 tests/junit_runner.py reports/junit.xml'
            }
        }
    }
}

This runs every step inside a fresh python:3.12-slim container on an agent that has Docker, so the build no longer depends on what is installed on the agent. Docker isn't available on my lab machine, so this example was not run. Agents and Distributed Builds covers labels, SSH agents and container agents.

Where you'll use this

Here is a complete release pipeline for logstats that combines the directives above: build and test on one executor with parallel checks, archive and stash the package, deploy to staging automatically, and deploy to production only when asked, after an approval, without holding an executor while waiting.

pipeline {
    agent none
 
    parameters {
        choice(name: 'TARGET_ENV', choices: ['staging', 'production'], description: 'How far to deploy')
    }
 
    options {
        timeout(time: 30, unit: 'MINUTES')
        buildDiscarder(logRotator(numToKeepStr: '30', artifactNumToKeepStr: '10'))
        disableConcurrentBuilds()
        timestamps()
    }
 
    environment {
        APP         = 'logstats'
        REPO_URL    = 'file:///home/sid/logstats'
        DEPLOY_ROOT = '/home/sid/deploy'
    }
 
    stages {
        stage('Build and test') {
            agent any
            stages {
                stage('Build') {
                    steps {
                        cleanWs()
                        git url: env.REPO_URL, branch: 'main'
                        sh 'python3 -m py_compile logstats.py'
                        sh 'mkdir -p dist && tar czf dist/$APP-$BUILD_NUMBER.tar.gz logstats.py'
                    }
                }
                stage('Checks') {
                    parallel {
                        stage('Unit tests') {
                            steps {
                                sh 'python3 tests/junit_runner.py reports/junit.xml'
                            }
                        }
                        stage('Sample report') {
                            steps {
                                sh 'python3 logstats.py sample/access.log > report.txt'
                            }
                        }
                    }
                }
            }
            post {
                always {
                    junit 'reports/*.xml'
                }
                success {
                    archiveArtifacts artifacts: 'dist/*.tar.gz, report.txt', fingerprint: true
                    stash name: 'package', includes: 'dist/*.tar.gz'
                }
            }
        }
 
        stage('Deploy to staging') {
            agent any
            steps {
                unstash 'package'
                sh 'mkdir -p $DEPLOY_ROOT/staging && tar xzf dist/$APP-$BUILD_NUMBER.tar.gz -C $DEPLOY_ROOT/staging'
            }
        }
 
        stage('Deploy to production') {
            when {
                beforeInput true
                expression { params.TARGET_ENV == 'production' }
            }
            options {
                timeout(time: 1, unit: 'HOURS')
            }
            input {
                message 'Deploy to production?'
                ok 'Deploy'
                submitter 'admin'
            }
            agent any
            steps {
                unstash 'package'
                sh 'mkdir -p $DEPLOY_ROOT/production && tar xzf dist/$APP-$BUILD_NUMBER.tar.gz -C $DEPLOY_ROOT/production'
            }
        }
    }
 
    post {
        success {
            echo "${env.APP} build ${env.BUILD_NUMBER} deployed to ${params.TARGET_ENV}"
        }
        failure {
            echo "Build failed: ${env.BUILD_URL}console"
        }
    }
}

The "deploy" is just tar xzf into a directory, so the example runs anywhere; in real life those two sh lines call your deployment tool. A production run, approved through the API, trimmed:

[Pipeline] { (Build and test)
[Pipeline] node
[2026-11-10T06:20:33.160Z] Running on Jenkins in /home/sid/.jenkins/workspace/logstats-release
[…]
[Pipeline] { (Build)
[Pipeline] cleanWs
[2026-11-10T06:20:33.429Z] [WS-CLEANUP] Deleting project workspace...
[…]
[2026-11-10T06:20:34.406Z] + tar czf dist/logstats-4.tar.gz logstats.py
[…]
[Pipeline] { (Checks)
[Pipeline] parallel
[…]
[2026-11-10T06:20:35.447Z] OK
[…]
Post stage
[Pipeline] junit
[2026-11-10T06:20:36.098Z] Recording test results
[…]
[Pipeline] stash
[2026-11-10T06:20:36.319Z] Stashed 1 file(s)
[…]
[Pipeline] { (Deploy to staging)
[…]
[2026-11-10T06:20:37.190Z] + tar xzf dist/logstats-4.tar.gz -C /home/sid/deploy/staging
[…]
[Pipeline] { (Deploy to production)
[Pipeline] timeout
[2026-11-10T06:20:37.554Z] Timeout set to expire in 1 hr 0 min
[Pipeline] {
[Pipeline] input
[2026-11-10T06:20:37.728Z] Deploy to production?
[2026-11-10T06:20:37.728Z] Deploy or Abort
[2026-11-10T06:20:37.899Z] Approved by admin
[Pipeline] node
[…]
[2026-11-10T06:20:38.522Z] + tar xzf dist/logstats-4.tar.gz -C /home/sid/deploy/production
[…]
[Pipeline] { (Declarative: Post Actions)
[Pipeline] echo
[2026-11-10T06:20:39.054Z] logstats build 4 deployed to production
[…]
Finished: SUCCESS

A staging-only run (the default parameter) logs Stage "Deploy to production" skipped due to when conditional and never shows the approval box, thanks to beforeInput true. The stage view of the production run:

Build and test	SUCCESS	296 ms
Build	SUCCESS	1223 ms
Checks	SUCCESS	257 ms
Unit tests	SUCCESS	539 ms
Sample report	SUCCESS	680 ms
Deploy to staging	SUCCESS	768 ms
Deploy to production	SUCCESS	1372 ms
Declarative: Post Actions	SUCCESS	246 ms

The cleanWs() at the start of Build wasn't in my first version. Without it, the second run's stash reported Stashed 2 file(s): the previous build's tarball was still in dist/. That is the same stale-workspace problem the freestyle and pipeline basics articles ran into, and it is the reason the first line of a build stage that produces artifacts should clean the workspace. The capstone extends this pipeline with real credentials, agents and a deployment target.

Common mistakes

Script security rejects a method. My first script block converted the rate with toBigDecimal(), and the second with new BigDecimal(...):

Scripts not permitted to use staticMethod org.codehaus.groovy.runtime.DefaultGroovyMethods toBigDecimal java.lang.String. Administrators can decide whether to approve or reject this signature.
[…]
org.jenkinsci.plugins.scriptsecurity.sandbox.RejectedAccessException: Scripts not permitted to use staticMethod org.codehaus.groovy.runtime.DefaultGroovyMethods toBigDecimal java.lang.String
Finished: FAILURE
Scripts not permitted to use new java.math.BigDecimal java.lang.String. Administrators can decide whether to approve or reject this signature.

Pipelines from SCM always run in the Groovy sandbox, and each rejected signature lands in Manage Jenkins → In-process Script Approval for an administrator to approve. Approving is sometimes right, but every approval widens what any Jenkinsfile on the controller may do. I tested the alternatives instead: toDouble(), toInteger() and as Double were allowed, while Double.parseDouble() was rejected too. The best fix is usually to move the logic out of Groovy.

Using branch outside a multibranch pipeline. when { branch 'main' } skipped Publish docs in a job that only ever builds main, with no warning beyond the usual skipped due to when conditional. In a plain Pipeline job, use expression with something you control, or move to multibranch.

Relying on parameters in the first build. The first build after adding parameters can't take -p values and sees empty environment variables (shown in parameters). If a first run could do damage with empty values, guard it with when { expression { currentBuild.previousBuild != null } }, or start the first build by hand once after creating the job.

Interpolating secrets with double quotes. sh "echo ${API_TOKEN}" produced the A secret was passed to "sh" using Groovy String interpolation, which is insecure warning. Single quotes, always.

Naming a tool that isn't configured. tools { jdk 'temurin-21' } fails before any stage runs with Tool type "jdk" does not have an install of "temurin-21" configured. The names must match Manage Jenkins → Tools exactly; the linter checks them.

Summary

  • environment sets variables (stage blocks override top-level ones); credentials() binds secrets, creates _USR/_PSW for username/password credentials, and masks values as ****. Reference secrets with single quotes.
  • parameters and triggers are registered by running the Jenkinsfile, so the first build after adding them can't use them. Read parameters through params.NAME.
  • Give every pipeline a top-level timeout (it ends the build ABORTED), use retry only for flaky external dependencies, and add disableConcurrentBuilds() to anything that deploys.
  • when skips stages visibly. branch only works in multibranch, changeset is false on a first build, and beforeAgent/beforeInput evaluate the condition before allocating an agent or asking a human.
  • parallel branches under one agent share a workspace; failFast stops siblings on the first failure; matrix runs one stage set per axis combination.
  • post runs in the order always, changed, fixed/regression, result, cleanup. fixed and regression are the right hooks for notifications.
  • Put input at stage level with agent none at the top and a timeout, so a waiting build holds no executor.
  • stash moves small files between stages of one build; script is an escape hatch that runs inside a sandbox, so keep it short.

Exercises

Exercise 1: Predict the post blockseasy

A job's last build was UNSTABLE. Which post conditions run, and in which order, if the next build (a) succeeds, (b) is UNSTABLE again? Check your answer against the table in post conditions.

Show Solution

(a) always, changed, fixed, success, cleanup. (b) always, unstable, cleanup. From builds #6 and #5 of the test job:

Started decl-post #6
post: always
post: changed
post: fixed
post: success
post: cleanup
Finished: SUCCESS
Started decl-post #5
post: always
post: unstable
post: cleanup
Finished: UNSTABLE

An unstable build followed by another unstable build is not "changed", so a notification hooked to changed or regression stays quiet. That is exactly what you want when a known-flaky test is already being worked on.

Exercise 2: Run tests only when code changesmedium

Write a pipeline whose Unit tests stage runs only when logstats.py or anything under tests/ changed since the last build. Prove it by committing a change to sample/access.log (tests skipped) and then to tests/test_logstats.py (tests run).

Show Solution
pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git url: 'file:///home/sid/logstats', branch: 'main'
            }
        }
        stage('Unit tests') {
            when {
                anyOf {
                    changeset 'logstats.py'
                    changeset 'tests/**'
                }
            }
            steps {
                sh 'python3 tests/junit_runner.py reports/junit.xml'
            }
        }
    }
}

Three builds, filtered to the interesting lines: the first build (no changelog), then after a commit to sample/access.log, then after a commit that added a test:

Warning, empty changelog. Probably because this is the first build.
Warning, empty changelog. Probably because this is the first build.
Stage "Unit tests" skipped due to when conditional
Finished: SUCCESS
Stage "Unit tests" skipped due to when conditional
Finished: SUCCESS
Ran 6 tests in 0.000s
Finished: SUCCESS

The first build prints the empty-changelog warning once per changeset condition. Be careful with this pattern on its own: a build triggered by hand with no new commits also skips the tests. If manual builds should always test, add a third condition to the anyOf, for example a booleanParam checked with expression.

Exercise 3: Skip one parallel branch on requestmedium

Add a booleanParam called SKIP_TESTS (default false) to a pipeline with two parallel branches, Unit tests and Sample report, so that Unit tests is skipped when the parameter is true while the other branch still runs.

Show Solution
pipeline {
    agent any
    parameters {
        booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: 'Skip the unit tests')
    }
    stages {
        stage('Checkout') {
            steps {
                git url: 'file:///home/sid/logstats', branch: 'main'
            }
        }
        stage('Checks') {
            parallel {
                stage('Unit tests') {
                    when { expression { !params.SKIP_TESTS } }
                    steps {
                        sh 'python3 tests/junit_runner.py reports/junit.xml 2>&1 | tail -1'
                    }
                }
                stage('Sample report') {
                    steps {
                        sh 'python3 logstats.py sample/access.log | head -1'
                    }
                }
            }
        }
    }
}

After one build to register the parameter, jcli build ex-skip-tests -s -v -p SKIP_TESTS=true printed (with the [Pipeline] bookkeeping lines filtered out):

[Pipeline] { (Checks)
[Pipeline] parallel
[Pipeline] { (Branch: Unit tests)
[Pipeline] { (Branch: Sample report)
[Pipeline] { (Unit tests)
[Pipeline] { (Sample report)
Stage "Unit tests" skipped due to when conditional
[Pipeline] getContext
[Pipeline] // stage
+ python3 logstats.py sample/access.log
+ head -1
requests: 12  unparsed: 2
[…]
Finished: SUCCESS

when works on each parallel branch independently. Use params.SKIP_TESTS rather than the environment variable so the first build behaves too.

Exercise 4: Approve without blocking an executorhard

This pipeline holds an executor for as long as nobody approves it. Rewrite it so that no executor is busy while it waits, and prove it with the computer API while the build is waiting.

pipeline {
    agent any
    stages {
        stage('Deploy to production') {
            steps {
                input message: 'Deploy this build to production?', ok: 'Deploy'
                sh 'echo deploying'
            }
        }
    }
}
Hint

Two changes: the top-level agent and where the input lives.

Show Solution
pipeline {
    agent none
    stages {
        stage('Deploy to production') {
            input {
                message 'Deploy this build to production?'
                ok 'Deploy'
            }
            agent any
            steps {
                sh 'echo deploying'
            }
        }
    }
}

While each version waited, I listed what every executor was running:

curl -g -sS -u "admin:$JENKINS_API_TOKEN" "http://localhost:8090/computer/api/json?tree=computer[displayName,executors[currentExecutable[url]]]" \
  | jq -c '[.computer[] | {node: .displayName, busy: [.executors[] | .currentExecutable.url // "idle"]}]'
[{"node":"Built-In Node","busy":["idle","http://localhost:8090/job/decl-step-input/1/"]}]

for the original, and for the rewrite:

[{"node":"Built-In Node","busy":["idle","idle"]}]

After approval, the rewrite allocated an executor and ran:

[Pipeline] { (Deploy to production)
[Pipeline] input
Deploy this build to production?
Deploy or Abort
Approved by admin
[Pipeline] node
Running on Jenkins in /home/sid/.jenkins/workspace/decl-stage-input
[Pipeline] {
[Pipeline] sh
+ echo deploying
deploying
[…]
Finished: SUCCESS

In production, also wrap the stage in options { timeout(...) } so a forgotten approval doesn't wait forever.


Tested with: Jenkins 2.580.2 (LTS) with Pipeline: Declarative 2.2293, Pipeline: Groovy 4403, Pipeline: Input Step 568, Timestamper 1.30 and Workspace Cleanup 0.49, on OpenJDK 21.0.13 (Temurin), Ubuntu 24.04 (WSL2), November 2026. Every Jenkinsfile in this article except the Docker agent example was run on that controller (Docker is not installed there, so agent { docker ... } was not executed). Approvals were submitted through the REST API instead of clicking Deploy, and the demo credentials were created with the CLI. Logs are trimmed where marked […]. What surprised me: when { branch } silently never matches outside multibranch, and the first build of a parameterized pipeline sees empty parameter variables in the shell. Paths from the test machine's scratch directories are shown shortened to /home/sid/…. Job, node and credential names are shown without the test run's prefixes.

Was this page helpful?
The Dark Debugger

Written by The Dark Debugger

Engineer documenting the things that took me too long to learn, so they take you less time. Every Jenkins tutorial here is tested end to end before publishing.