In this article, I want to explain When Conditions in Jenkins pipelines. Suppose you want to execute pipeline stages when a condition or some conditions are met. How can you do that? The answer is When Conditions.
If you are interested in this tutorial series, STAR the following GitHub repo.
This repo is a particular repo that I created for this tutorial:
Execution of the pipeline stages can be controlled with conditions. These conditions must be defined in the when block within each stage. Jenkins supports a set of conditions that can be defined to limit stage execution. Each when block must contain at least one condition. If more than one condition is declared in the when block, all conditions should return true for executing that stage. Moreover, more complex conditions can be defined using the nested conditions.
In the above example, the Test stage is run only once at the first run of the pipeline job. This stage will not be run in the subsequent runs of the pipeline.
Conditions natively supported by Jenkins are called Built-in conditions. In addition to those conditions, some plugins may add more conditions.
branch checks the source code’s branch name with the given pattern. The stage will be executed if the branch name matches the pattern. You should note that this condition only works in Multibranch pipelines.
The Test stage in the below example executes when the branch name is started with “release-” all ANT-style patterns are accepted.
buildingTag runs the following stage if the current git commit has a tag.
An unfixed Jenkins bug affects this condition; if you see it didn’t work, you should manually set the TAG_NAME environment variable.
changelog gets a regular expression and matches it with the message of the last git commit. If the message matches the given pattern, the following stage gets executed. You should note that this condition works only in Multibranch pipelines, and pipeline code, Jenkinsfile, should be written from the SCM repository. In the below example, the stage is run when the git commit message contains Test string.
changeset looks for changes with the given pattern. It watches the last git commit, and if any files/directories are changed with the given pattern, the stage will be executed.
environment checks the environment variable value.
equals runs the stage if the actual value equals the expected one. For example, the stage is executed if the current build number is one.
expression gets a Groovy language expression and runs the stage if that expression evaluates true. In the case of strings, all values, including 0 and false, return true. For strings to be considered as false, value should be null.
tag runs the stage if the TAG_NAME variable matches the given pattern. If the pattern is empty, it runs the stage if the TAG_NAME variable exists.
triggeredBy executes the stage when the pipeline gets triggered by something/someone you mentioned. Really helpful for notification purposes.
Jenkins Complex Conditions:
Complex conditions are usually a set of conditions explained above. Jenkins supports three complex/nested conditions. not, allOf and anyOf are complex conditions that are used in conjunction with standard conditions.
not executes the stage if the nested condition is false.
allOf executes the stage if all nested conditions are true.
anyOf executes the stage if at least one nested condition is true.
When is the when directive gets evaluated?
By default, the when directive is evaluated after agent, input and options directives. You can change those with beforeAgent, beforeInput and beforeOptions within the when block.
The Jenkins CI is a great and rich tool for implementing CI/CD pipelines. Sometimes, you may find it very complex, but it doesn’t. You should own day-to-day practices to make your knowledge solid. Comment your questions below.
You can find all tutorial materials in the following GitHub repository: