Stage conditions with when directive in Jenkins - Commands & Configuration

Introduction

Sometimes you want parts of your Jenkins pipeline to run only if certain things are true. The when directive helps you decide if a stage should run or be skipped based on conditions.

When you want to run tests only on the main branch but skip on others

When you want to deploy only if the build was successful

When you want to run a stage only during working hours

When you want to skip a stage if a certain file hasn't changed

When you want to run a stage only if an environment variable has a specific value

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo 'Building...'
      }
    }
    stage('Test') {
      when {
        branch 'main'
      }
      steps {
        echo 'Testing on main branch only'
      }
    }
    stage('Deploy') {
      when {
        expression { return currentBuild.result == null || currentBuild.result == 'SUCCESS' }
      }
      steps {
        echo 'Deploying only if build succeeded'
      }
    }
  }
}

This Jenkinsfile defines a pipeline with three stages: Build, Test, and Deploy.

The when directive in the Test stage ensures it runs only on the 'main' branch.

The Deploy stage uses an expression condition to run only if the build succeeded or has no result yet.

Commands

This command updates the Jenkins pipeline with the Jenkinsfile containing the when conditions to control stage execution.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully

Starts the Jenkins pipeline job named 'my-pipeline' to run the stages with the when conditions applied.

Terminal

jenkins-cli build my-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] stage

[Pipeline] { (Build)

Building...

[Pipeline] }

[Pipeline] // stage

[Pipeline] stage

[Pipeline] { (Test)

Testing on main branch only

[Pipeline] }

[Pipeline] // stage

[Pipeline] stage

[Pipeline] { (Deploy)

Deploying only if build succeeded

[Pipeline] }

[Pipeline] // stage

[Pipeline] End of Pipeline

Finished: SUCCESS

Shows the console output of the last run of the 'my-pipeline' job to verify which stages ran based on the when conditions.

Terminal

jenkins-cli console my-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] stage

[Pipeline] { (Build)

Building...

[Pipeline] }

[Pipeline] // stage

[Pipeline] stage

[Pipeline] { (Test)

Testing on main branch only

[Pipeline] }

[Pipeline] // stage

[Pipeline] stage

[Pipeline] { (Deploy)

Deploying only if build succeeded

[Pipeline] }

[Pipeline] // stage

[Pipeline] End of Pipeline

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: the when directive controls if a stage runs by checking simple conditions like branch name or build status.

Common Mistakes

Using when conditions without proper syntax like missing braces or quotes

Jenkins will fail to parse the Jenkinsfile and the pipeline won't run

Always use correct syntax, for example: when { branch 'main' } or when { expression { return true } }

Expecting stages to run when conditions are false

Stages with when conditions that evaluate to false are skipped and do not run

Design your pipeline knowing that when conditions skip stages if false

Using currentBuild.result in when expression without checking for null

If currentBuild.result is null (build in progress), the expression may fail or behave unexpectedly

Check for null explicitly like: currentBuild.result == null || currentBuild.result == 'SUCCESS'

Summary

Use the when directive in Jenkinsfile stages to run them conditionally.

Common conditions include branch name and build success status.

Run the pipeline and check console output to verify which stages executed.