Jenkins Declarative Pipeline [With Examples]: Detailed Guide

What is Jenkinsfile?

A Jenkinsfile is a text file used in the Jenkins automation server to define and describe the entire build and deployment process for a software project. It is written in a domain-specific language called Groovy and serves as a blueprint for Jenkins to automate tasks such as building, testing, and deploying software applications.

Jenkinsfiles are typically stored within the version control repository of a project, allowing developers to manage and version the build and deployment pipeline alongside their code. This approach provides transparency and reproducibility in the software development and continuous integration/continuous deployment (CI/CD) processes.

Jenkinsfile can be written in two aspects – Scripted pipeline syntax & Declarative pipeline syntax

What is Jenkins Scripted Pipeline?

Jenkins pipelines are traditionally written as scripted pipelines. Ideally, the scripted pipeline is stored in Jenkins webUI as a Jenkins file. The end-to-end scripted pipeline script is written in Groovy.

• It requires knowledge of Groovy programming as a prerequisite.
• Jenkinsfile starts with the word node.
• Can contain standard programming constructs like if-else block, try-catch block, etc.

Sample Scripted Pipeline

node {
    stage('Stage 1') {
        echo 'hello'
    }
}

Jenkins Declarative Pipeline Syntax

In this section, we will look at the most commonly used Jenkins declarative pipeline examples or syntax. Typically, declarative pipelines contain one or more declarative steps or directives, as explained below.

pipeline

Entire Declarative pipeline script should be written inside the pipeline block. It’s a mandatory block.

pipeline {
}

agent

Specify where the Jenkins build job should run. agent can be at pipeline level or stage level. It’s mandatory to define an agent.

Possible values-

• any – Run Job or Stage on any available agent.

pipeline {
     agent any
}

• none – Don’t allocate any agent globally for the pipeline. Every stage should specify their own agent to run.

pipeline {
     agent none
}

• label – Run the job in agent which matches the label given here. Remember Jenkins CI/CD can work on Master/Agent architecture. Master nodes can delegate the jobs to run in Agent nodes. Nodes on creation given a name & label to identify them later.

  E.g All linux nodes can be labeled as linux-machine

pipeline {
       agent {
           label 'linux-machine'
       }
}

• docker – Run the job in given Docker container

  A sample can be found here at GitHub.

stages

stages block constitutes different executable stage blocks. At least one stage block is mandatory inside stages block.

pipeline {
       agent {
           label 'linux-machine'
       }
     stages {
     }
}

stage

stage block contains the actual execution steps. Stage block has to be defined within stages block. It’s mandatory to have at least one stage block inside the stage block. Also its mandatory to name each stage block & this name will be shown in the Stage View after we run the job.

In below example, the stage is named as “build step”

pipeline {
       agent {
           label 'linux-machine'
       }
     stages {
         stage('build step') {
         }
     }
}

A sample can be found here at GitHub.

steps

steps block contains the actual build step. It’s mandatory to have at least one step block inside a stage block.

Depending on the Agent’s operating system (where Jenkins job runs), we can use shell, bat, etc., inside the steps command.

pipeline {
     agent any
     stages {
         stage('build step') {
              steps {
                 echo "Build stage is running"
              }
         }
     }
}

Scripted Pipeline in Jenkins job

Sample can be found here at GitHub.

parameters

The parameters directive provides a way for Jenkins job to interact with Jenkins CI/CD users during the running of the build job.

parameter can be of the following types – string, text, booleanParam, choice & password

string – Accepts a value of String type from Jenkins user.

E.g.string(name: ‘NAME’, description: ‘Please tell me your name?’)

text – Accepts multi line value from Jenkins user E.g.text(name: ‘DESC’, description: ‘Describe about the job details’)

booleanParam – Accepts a true/false value from Jenkins user E.g.booleanParam(name: ‘SKIP_TEST’, description: ‘Want to skip running Test cases?’)

choice – Jenkins user can choose one among the choices of value provided E.g.choice(name: ‘BRANCH’, choices: [‘Master’, ‘Dev’], description: ‘Choose the branch’)

password – Accepts a secret like password from Jenkins user E.g.password(name: ‘SONAR_SERVER_PWD’, description: ‘Enter SONAR password’)

Let’s look at a sample on how to use parameters directive-

pipeline {
    agent any
    parameters {
        string(name: 'NAME', description: 'Please tell me your name?')

        text(name: 'DESC', description: 'Describe about the job details')

        booleanParam(name: 'SKIP_TEST', description: 'Want to skip running Test cases?')

        choice(name: 'BRANCH', choices: ['Master', 'Dev'], description: 'Choose branch')

        password(name: 'SONAR_SERVER_PWD', description: 'Enter SONAR password')
    }
    stages {
        stage('Printing Parameters') {
            steps {
                echo "Hello ${params.NAME}"

                echo "Job Details: ${params.DESC}"

                echo "Skip Running Test case ?: ${params.SKIP_TEST}"

                echo "Branch Choice: ${params.BRANCH}"

                echo "SONAR Password: ${params.SONAR_SERVER_PWD}"
            }
        }
    }
}

If a parameters directive is used in the pipeline, Jenkins CI/CD can sense that it needs to accept the user’s input while running the job. Hence Jenkins will change the Build now link in the left side menu to Build with parameters link.

When we click on the Build with Parameters link, Jenkins CI/CD will let us pass values for the parameters we configured in the declarative pipeline.

Once we enter each parameter’s values, we can hit the build button to run the job.

script

script block helps us run Groovy code inside the Jenkins declarative pipeline.

pipeline {
    agent any
    parameters {
        string(name: 'NAME', description: 'Please tell me your name')
        choice(name: 'GENDER', choices: ['Male', 'Female'], description: 'Choose Gender')
    }
    stages {
        stage('Printing name') {
            steps {
                script {
                    def name = "${params.NAME}"
                    def gender = "${params.GENDER}"
                    if(gender == "Male") {
                        echo "Mr. $name"    
                    } else {
                        echo "Mrs. $name"
                    }
                }
            }
        }
   }
}

script block is wrapped inside the steps block. In the above example, we are printing the name passed as parameter suffixed with Mr. or Mrs. based on the Gender chosen.

We used build with parameters to pass params at the time of running the job.

when

Acts like if condition to decide whether to run the particular stage or not . Its an optional block.

• when block

pipeline {
     agent any
     stages {
         stage('build') {
              when {
                  branch 'dev'             
              }
              steps {
                 echo "Working on dev branch"
              }
         }
     }
}


• when block using Groovy expression

pipeline {
     agent any
     stages {
         stage('build') {
              when {
                  expression {
                     return env.BRANCH_NAME == 'dev';
                  }             
              }
              steps {
                 echo "Working on dev branch"
              }
         }
     }
}


• when block with environment variables

pipeline {
    agent any
    environment { 
        DEPLOY_TO = 'production'
    }
    stages {
        stage('Welcome Step') {
            	when { 
    environment name: 'DEPLOY_TO', value: 'production'
}
            steps { 
                echo 'Welcome to LambdaTest'
            }
        }
    }
}


• when block with multiple conditions & all conditions should be satisfied

pipeline {
    agent any
    environment { 
        DEPLOY_TO = 'production'
    }
    stages {
        stage('Welcome Step') {
            when { 
                allOf { 
                    branch 'master'; 
                    environment name: 'DEPLOY_TO', value: 'production'
                } 
            }
            steps { 
                echo 'Welcome to LambdaTest'
            }
        }
    }
}


• when block with multiple conditions & any of the given conditions should be satisfied

pipeline {
    agent any
    environment { 
        DEPLOY_TO = 'production'
    }
    stages {
        stage('Welcome Step') {
            when { 
                anyOf { 
                    branch 'master';
                    branch 'staging' 
                } 
            }
            steps { 
                echo 'Welcome to LambdaTest'
            }
        }
    }
}

Sample can be found here at GitHub.

tools

This block lets us add pre configured tools like Maven or Java to our job’s PATH. It’s an optional block.

To use any tool, they have to be pre-configured under the Global Tools Configuration section. For this example, let’s see how to configure Maven. You can also refer to our Jenkins Maven integration tutorial for more information.

Step 1: Open Jenkins Server URL (http://localhost:8080)

Step 2: Click on Manage Jenkins from the left sidebar menu.

Step 3: Click on Global Tools Configuration under System Configuration.

Step 4: Scroll down to the Maven section & click on Maven Installations.

Step 5: Click on the Add Maven button. Enter the following values in the configuration.

• Name – Maven 3.5.0
• MAVEN_HOME – Enter the maven installation path in local

Alternatively we can download Maven from Internet instead of pointing to the local installation path by enabling the Install Automatically checkbox.

Step 6: Click on Add Installer button & choose Install from Apache.

Step 7: Choose the Maven version to download. We have chosen the Maven version 3.6.3.

Step 8: Click on the Save button.

Refer to Maven tool in Pipeline in tools block with the name we used while configuring in Global Tools Configuration (MAVEN_PATH in this example).

pipeline {
    agent any
    tools {
        maven 'MAVEN_PATH' 
    }
    stages {
         stage('Load Tools') {
              steps {
                 sh "mvn -version"
              }
         }
     }
}

Sample can be found here at GitHub.

Console Output-

Run the job & we should see the mvn -version command response in console output-

Similarly we can also configure & use tools like Java, Gradle, Git etc from tools block in pipeline code.

parallel

parallel blocks allow us to run multiple stage blocks concurrently. It’s ideal to parallelize stages which can run independently. We can define agents for each stage within a parallel block, so each stage will run on its own agent.

Example- When we want to run a piece of script in windows agent & another script in linux agent as part of the build, we can make them run concurrently using parallel blocks.

pipeline {
    agent any
    stages {
           stage('Parallel Stage') {
              parallel {
                stage('windows script') {
                    agent {
                        label "windows"
                    }
                    steps {
                        	echo "Running in windows agent"
		bat 'echo %PATH%'
                    }
                }
                stage('linux script') {
                    agent {
                        label "linux"
                    }
                    steps {
                       sh "Running in Linux agent"
                    }
                }
             }
        }
    }
}

Sample can be found here at GitHub.

post

post block contains additional actions to be performed on completion of the pipeline execution. It can contain one or many of the following conditional blocks – always, changed, aborted, failure, success, unstable etc.

post block conditions

always – run this post block irrespective of the pipeline execution statuschanged – run this post block only if the pipeline’s execution status is different from the previous build run. E.g., the build failed at an earlier run & ran successfully this time.aborted – if the build is aborted in the middle of the run. Usually due to manual stopping of the build runfailure – if the build status is failuresuccess – if the build ran successfullyunstable – build is successful but not healthy. E.g. On a particular build run, test cases ran successfully, but test coverage % is less than expected, then the build can be marked as unstable

Example-

pipeline {
     agent any
     stages {
         stage('build step') {
              steps {
                 echo "Build stage is running"
              }
         }
     }
     post {
         always {
             echo "You can always see me"
         }
         success {
              echo "I am running because the job ran successfully"
         }
         unstable {
              echo "Gear up ! The build is unstable. Try fix it"
         }
         failure {
             echo "OMG ! The build failed"
         }
     }
}

Sample can be found here at GitHub.

Marking build as Unstable

There are scenarios where we don’t want to mark build as failure but want to mark build as unstable.

Example- When test case coverage doesn’t cross the threshold we expect, we can mark the build as UNSTABLE.

pipeline {
    agent any
    tools {
        maven 'MAVEN_PATH'
        jdk 'jdk8'
    }
    stages {
        stage("Tools initialization") {
            steps {
                sh "mvn --version"
                sh "java -version"
            }
        }
        stage("Checkout Code") {
            steps {
                git branch: 'master',
                url: "https://github.com/iamvickyav/spring-boot-data-H2-embedded.git"
            }
        }
        stage("Building Application") {
            steps {
               sh "mvn clean package"
            }
        }
        stage("Code coverage") {
           steps {
               jacoco(
                    execPattern: '**/target/**.exec',
                    classPattern: '**/target/classes',
                    sourcePattern: '**/src',
                    inclusionPattern: 'com/iamvickyav/**',
                    changeBuildStatus: true,
                    minimumInstructionCoverage: '30',
                    maximumInstructionCoverage: '80')
               }
           }
        }
 }

Sample can be found here at GitHub.

jacoco() is a special method which helps us configure Jacoco reports including the minimum & maximum coverage threshold. In the above example, min coverage (minimumInstructionCoverage) check is set as 30 & max coverage (maximumInstructionCoverage) check is set as 80.

So if the code coverage is-

Less than 30 – Build will be marked as Failure.Between 30 & 80 – Build will be marked as Unstable.Above 80 – Build will be marked as Success.

What Does the Options Block Do in a Jenkins Declarative Pipeline?

The options block sets pipeline-wide behavior instead of a single stage: build retention, timeouts, retries, and concurrent-run limits. It sits inside the pipeline block next to agent and stages, and it is optional.

Some of the most commonly used options directives are:

pipeline {
    agent any
    options {
        buildDiscarder(logRotator(numToKeepStr: '10'))
        timeout(time: 1, unit: 'HOURS')
        disableConcurrentBuilds()
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

The full list of options directives is in Jenkins' own Pipeline syntax reference.

triggers

Instead of triggering the build manually, we can configure build to run in certain time intervals using the triggers block. We can use the special method called cron() within triggers block to configure the build schedule.

Understanding cron

Cron configuration contains 5 fields representing minute (0-59), hour (0-23), day of the month (1-31), month (1-12), day of the week (0-7)

Example-

Every 15 minutes – H/15 * * * * Every 15 minutes but only between Monday & Friday – H/15 * * * 1-5

pipeline {
    agent any
    triggers {
        cron('H/15 * * * *')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

Sample can be found here at GitHub.

Conclusion

In this blog, we have done an in-depth dive into Jenkins Declarative pipeline examples and their usage. Instead of configuring build steps using UI in a remote Jenkins portal, we would always recommend you to prefer creating Jenkinsfile with Declarative pipeline syntax. Jenkinsfile, since part of the application’s source code, will provide more control over CI/CD steps to developers. The same Jenkinsfile can also call the CLI of TestMu AI's HyperExecute in a test stage to split a suite across parallel virtual machines. That’s the best way to make the most of Jenkins CI/CD and all the features it has to offer!

Happy building & testing!