Skip to main content
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

ConditionDescriptionExample
branchMatches the current branch namebranch 'main'
environmentChecks an environment variable’s valueenvironment name: 'deploy', value: 'pre-prod'
expressionEvaluates any Groovy boolean expressionexpression { params.MANUAL_TEST }
changeRequestTriggers when the build is a pull requestchangeRequest()
buildingTagRuns only on builds started by a Git tagbuildingTag()
tagMatches a specific tag patterntag '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: '[email protected]'
    }
    steps {
        echo 'This PR was opened by [email protected].'
    }
}

​
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.'
    }
}

​
Further Reading

Watch Video