We can use the when expression in a Jenkinsfile to specify the conditions under which a particular build step or post-build action should be executed. It allows you to specify a Boolean expression that determines whether the build step or post-build action should be run.
This tutorial covers the basics of using the when expression when it comes to Jenkins pipelines.
Jenkins When Expression
The when expression must contain at least one Boolean condition. You can also combine multiple conditions, but all the specified conditions must evaluate true for the block to run.
The following shows the syntax of the when expression in Jenkins:
<condition>
}
In this case, the <condition> specifies the Boolean expression that is evaluated before running or not running the build step or post-build action.
There are several types of conditions that you can use in the when expression including the following:
- Branch – It specifies a branch name or a regular expression that is used to match against the current branch.
- expression – It specifies a Groovy expression that is evaluated to determine whether the build step or post-build action should be run.
- not – It negates the condition that follows it.
- allOf – It specifies that all of the conditions that follow it must be true for the build step or post-build action to be run.
- anyOf – It specifies that at least one of the conditions that follow it must be true for the build step or post-build action to be run.
Let us look at an example pipeline on how we can use the when expression in Jenkins.
Example 1: Basic Example
The following pipeline demonstrates a basic example usage of the when expression in Jenkins:
agent any
parameters {
booleanParam(name: 'RUN_BUILD', defaultValue: false)
}
stages {
stage('Build') {
when {
expression { return params.RUN_BUILD }
}
steps {
echo ‘ Run Build is set to true’
}
}
}
}
In the provided example pipeline, the Build stage is only executed when the RUN_BUILD parameter is true. By default, the value of the RUN_BUILD parameter is false. In this case, the step is skipped as shown in the following console output:
If we change the value of the RUN_BUILD parameter to true, the build step is executed as shown in the following:
agent any
parameters {
booleanParam(name: 'RUN_BUILD', defaultValue: true)
}
stages {
stage('Build') {
when {
expression { return params.RUN_BUILD }
}
steps {
echo 'Run Build is true'
}
}
}
}
The resulting console output is as follows:
In this case, the echo message in the build step is executed.
Example 2: Using Not
We can also use the not condition to negate the result of a given expression as demonstrated in the following pipeline:
agent any
parameters {
booleanParam(name: 'RUN_BUILD', defaultValue: false)
}
stages {
stage('Build') {
when {
not {
expression { return params.RUN_BUILD }
}
}
steps {
// build steps go here
}
}
}
}
With this modification, the Build stage is only run if the RUN_BUILD parameter is false.
Example 3: Using the AllOf Conditional
Using the allOf condition, all the specified expression must evaluate to true for the step to run.
when {
allOf {
expression1
expression2
}
}
Conclusion
The when expression in Jenkins is a conditional statement that allows you to specify the conditions under which a build step or post-build action should be executed.
It allows you to use the Boolean expressions to control the execution of your pipeline, making it more flexible and adaptable to different build scenarios. You can use the when expression to specify a single condition or to combine multiple conditions using logical operators such as && (and) and || (or). Feel free to explore the documentation for more.
