Mastering Jenkins Declarative Pipeline Syntax: A Complete Guide

Jenkins offers two ways to define pipeline code: scripted and declarative. The scripted pipeline (also called "traditional" pipeline) uses Groovy as its DSL, while the declarative pipeline provides a simplified, user‑friendly syntax with dedicated statements, eliminating the need to learn Groovy.

Support for declarative pipelines was introduced in Pipeline Plugin version 2.5.

Declarative Pipeline Syntax

A declarative pipeline must start with the pipeline statement and include the following required parts:

agent

stages

stage

steps

Additional optional directives are also available:

environment (pipeline‑ or stage‑level)

input (stage‑level)

options (pipeline‑level)

parallel

parameters (pipeline‑level)

post

script

tools (pipeline‑ or stage‑level)

triggers

when (stage‑level)

agent

Jenkins distributes builds to "agent" nodes, allowing a single Jenkins master to run multiple projects while workloads are delegated to agents. An agent can be labeled (e.g., Linux, Windows) for easy identification. Specifying agent any runs the job on any available node.

pipeline {
    agent any
    ...
}

stages

The stages block defines distinct phases that appear as separate sections during execution.

pipeline {
    agent any
    stages {
        ...
    }
}

stage

At least one stage must be defined inside stages. Each stage is named and displayed in the Jenkins UI.

pipeline {
    agent any
    stages {
        stage('build') { ... }
        stage('test: integration-& quality') { ... }
        stage('test: functional') { ... }
        stage('test: load-& security') { ... }
        stage('approval') { ... }
        stage('deploy:prod') { ... }
    }
}

steps

The steps block, defined inside a stage, must contain at least one step. For Linux/macOS you can use sh:

steps {
    sh 'echo "A one line step"'
    sh '''
        echo "A multiline step"
        cd /tests/results
        ls -lrt
    '''
}

For Windows you can use bat or powershell:

steps {
    bat "mvn clean test -Dsuite=SMOKE_TEST -Denvironment=QA"
    powershell ".\funcional_tests.ps1"
}

environment

Define environment variables at the pipeline or stage level. Pipeline‑level definitions apply to all steps; stage‑level definitions apply only within that stage.

pipeline {
    agent any
    environment {
        OUTPUT_PATH = './outputs/'
    }
    stages {
        stage('build') { ... }
    }
}

pipeline {
    agent any
    stages {
        stage('build') {
            environment {
                OUTPUT_PATH = './outputs/'
            }
            ...
        }
    }
}

input

The input directive pauses a stage until a user manually confirms. Options include message (required), id, ok, submitter, submitterParameter, and parameters.

pipeline {
    agent any
    stages {
        stage('build') {
            input {
                message "Press Ok to continue"
                submitter "user1,user2"
                parameters {
                    string(name: 'username', defaultValue: 'user', description: 'Username of the user pressing Ok')
                }
            }
            steps {
                echo "User: ${username} said Ok."
            }
        }
    }
}

options

Defined at the pipeline level, options groups specific pipeline‑wide settings such as buildDiscarder, disableConcurrentBuilds, retry, timeout, etc. Example – retry the pipeline up to three times on failure:

pipeline {
    agent any
    options { retry(3) }
    stages { echo 'do something' }
}

parallel

Parallel execution allows multiple branches to run simultaneously within a stage. Example using the newer syntax (pipeline 1.2+):

pipeline {
    agent none
    stages {
        stage('Run Tests') {
            parallel {
                stage('Test On Windows') {
                    agent { label "windows" }
                    steps { bat "run-tests.bat" }
                }
                stage('Test On Linux') {
                    agent { label "linux" }
                    steps { sh "run-tests.sh" }
                }
            }
        }
    }
}

Limitations: a stage cannot have both parallel and steps, a parallel stage cannot contain another parallel, and stages with parallel cannot define agent or tools.

parameters

Define a list of parameters available to the pipeline at trigger time. Only one parameters block is allowed, placed at the pipeline level. Supported types include string and booleanParam:

pipeline {
    agent any
    parameters {
        string(name: 'user', defaultValue: 'John', description: 'A user that triggers the pipeline')
    }
    stages {
        stage('Trigger pipeline') {
            steps { echo "Pipeline triggered by ${params.USER}" }
        }
    }
}

post

The post block runs after a stage or the entire pipeline finishes. Conditions include always, changed, fixed, regression, aborted, failure, success, and unstable. Example:

pipeline {
    agent any
    stages { stage('Some steps') { steps { echo 'do something' } } }
    post { always { echo "Pipeline finished"; bat './performCleanUp.bat' } }
}

script

The script step allows insertion of scripted pipeline code inside a declarative stage, enabling advanced functionality and shared library usage.

pipeline {
    agent any
    stages {
        stage('Sample') {
            steps {
                echo "Scripted block"
                script {
                    // additional Groovy code here
                }
            }
        }
    }
}

tools

Specify tool versions (Maven, JDK, Gradle) at the pipeline or stage level. The tools must be configured in Jenkins' Global Tool Configuration.

pipeline {
    agent any
    tools { maven 'apache-maven-3.0.1' }
    stages { echo 'do something' }
}

triggers

Automatic pipeline execution can be configured with cron, pollSCM, or upstream triggers.

pipeline {
    agent any
    triggers { cron('0 */4 * * 1-5') }
    stages { ... }
}

pipeline {
    agent any
    triggers { pollSCM('0 */4 * * 1-5') }
    stages { ... }
}

pipeline {
    agent any
    triggers { upstream(upstreamProjects: 'job1, job2', threshold: hudson.model.Result.SUCCESS) }
    stages { ... }
}

when

The when directive conditionally executes a stage based on defined criteria, such as branch name. Example for running a stage only on the master branch:

pipeline {
    agent any
    stages {
        stage('Deploy stage') {
            when { branch 'master' }
            steps { echo 'Deploy master to stage' }
        }
    }
}

Final Jenkins Declarative Pipeline Tips

Syntax errors are reported at the start of the script, saving time by catching mistakes early. Declarative pipelines build on scripted pipelines; you can extend them with script steps when needed. Jenkins pipelines are widely used in CI/CD environments, offering many advantages regardless of whether you choose declarative or scripted syntax.