Built in when conditions

In Jenkins Declarative Pipelines, the when directive controls whether a stage should be executed. A stage with a when block runs only if at least one of its conditions evaluates to true. You can also combine conditions for more advanced logic.

Using when conditions can help you skip unnecessary stages, save build time, and reduce resource consumption.

Base Pipeline Example

Below is a simple pipeline without any conditional logic. It has three sequential stages that always run:

pipeline {
    agent any
    stages {
        stage('Stage-1') {
            steps {
                echo 'Stage-1'
            }
        }
        stage('Stage-2') {
            steps {
                echo 'Stage-2'
            }
        }
        stage('Stage-3') {
            steps {
                echo 'Stage-3'
            }
        }
    }
}

Overview of Built-in `when` Conditions

Condition	Description	Example
branch	Matches the current branch name	`branch 'main'`
environment	Checks an environment variable’s value	`environment name: 'deploy', value: 'pre-prod'`
expression	Evaluates any Groovy boolean expression	`expression { params.MANUAL_TEST }`
changeRequest	Triggers when the build is a pull request	`changeRequest()`
buildingTag	Runs only on builds started by a Git tag	`buildingTag()`
tag	Matches a specific tag pattern	`tag 'feature-*'`

Basic `when` Examples

1. Branch Selection

Run a stage only on the main branch:

stage('Run on main') {
    when {
        branch 'main'
    }
    steps {
        echo 'This runs only on the main branch.'
    }
}

2. Environment Variable Check

Execute the stage if DEPLOY equals pre-prod:

stage('Pre-prod deployment') {
    when {
        environment name: 'DEPLOY', value: 'pre-prod'
    }
    steps {
        echo "Deploying to pre-prod because DEPLOY=$DEPLOY"
    }
}

3. Groovy Expression

Use a custom Groovy expression to gate a manual test stage:

stage('Manual test stage') {
    when {
        expression {
            return params.MANUAL_TEST == true
        }
    }
    steps {
        echo 'Manual test parameter is true.'
    }
}

Avoid placing expensive computations or external calls in expression blocks—they run during pipeline evaluation and can slow down the build.

4. Pull Request Builds

Run validations only for pull requests:

stage('PR validation') {
    when {
        changeRequest()
    }
    steps {
        echo 'Running validations on pull request.'
    }
}

Filter by Author Email

stage('PR by Alice') {
    when {
        changeRequest authorEmail: 'alice@kk.com'
    }
    steps {
        echo 'This PR was opened by alice@kk.com.'
    }
}

5. Tag Checks

Any Tag Build

stage('Tag build') {
    when {
        buildingTag()
    }
    steps {
        echo 'Building from a tag, not a branch or commit.'
    }
}

Specific Tag Pattern

stage('Feature tag build') {
    when {
        tag 'feature-*'
    }
    steps {
        echo 'Running on a feature-* tag.'
    }
}

Advanced Condition Combinations

Evaluate Before Agent Allocation

Avoid checking out the workspace unless needed by evaluating conditions before the agent is allocated:

stage('Sandbox only') {
    when {
        beforeAgent true
        branch 'sandbox'
    }
    agent any
    steps {
        echo 'This runs on sandbox without checking out workspace on other branches.'
    }
}

Negation

Invert a condition to exclude certain branches:

stage('Exclude pre-prod') {
    when {
        not {
            branch 'pre-prod'
        }
    }
    steps {
        echo 'This runs on all branches except pre-prod.'
    }
}

anyOf

Run the stage if at least one nested condition is true:

stage('UAT or QA') {
    when {
        anyOf {
            branch 'uat'
            branch 'qa'
        }
    }
    steps {
        echo 'This runs on either uat or qa branch.'
    }
}

allOf

Run the stage only if all nested conditions are met:

stage('Main pre-prod') {
    when {
        allOf {
            branch 'main'
            environment name: 'DEPLOY', value: 'pre-prod'
        }
    }
    steps {
        echo 'This runs only on main branch when DEPLOY=pre-prod.'
    }
}

Introduction and Basics

Jenkins Setup and Interface

Extending Jenkins and Administration

Jenkins Pipelines

Automation and Security

Setting up CI Pipeline

Code Quality and Testing

Containerization and Deployment

Kubernetes and GitOps

AWS Lambda and Advanced Deployment Techniques

Jenkins Administration and Monitoring - Part 1

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring - Part 2

Backup and Configuration Management

Built in when conditions

Base Pipeline Example

Overview of Built-in `when` Conditions

Basic `when` Examples

1. Branch Selection

2. Environment Variable Check

3. Groovy Expression

4. Pull Request Builds

Filter by Author Email

5. Tag Checks

Any Tag Build

Specific Tag Pattern

Advanced Condition Combinations

Evaluate Before Agent Allocation

Negation

anyOf

allOf

Further Reading

Watch Video

​Base Pipeline Example

​Overview of Built-in when Conditions

​Basic when Examples

​1. Branch Selection

​2. Environment Variable Check

​3. Groovy Expression

​4. Pull Request Builds

​Filter by Author Email

​5. Tag Checks

​Any Tag Build

​Specific Tag Pattern

​Advanced Condition Combinations

​Evaluate Before Agent Allocation

​Negation

​anyOf

​allOf

​Further Reading

Watch Video

Base Pipeline Example

Overview of Built-in `when` Conditions

Basic `when` Examples

1. Branch Selection

2. Environment Variable Check

3. Groovy Expression

4. Pull Request Builds

Filter by Author Email

5. Tag Checks

Any Tag Build

Specific Tag Pattern

Advanced Condition Combinations

Evaluate Before Agent Allocation

Negation

anyOf

allOf

Further Reading