Conditional deployment logic in Jenkins - Commands & Configuration

Introduction

Sometimes you want your deployment to happen only if certain conditions are met, like only deploying to production if tests pass. Conditional deployment logic helps you control when parts of your Jenkins pipeline run, so you avoid mistakes and save time.

When you want to deploy to production only if all tests succeed.

When you want to skip deployment on weekends or outside business hours.

When you want to deploy to different environments based on the branch name.

When you want to run deployment steps only if a specific file changed in the commit.

When you want to avoid deploying if a manual approval step was not confirmed.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  environment {
    TEST_RESULT = ''
  }
  stages {
    stage('Build') {
      steps {
        echo 'Building the application'
      }
    }
    stage('Test') {
      steps {
        echo 'Running tests'
        script {
          // Simulate test result
          env.TEST_RESULT = 'SUCCESS'
        }
      }
    }
    stage('Deploy') {
      when {
        expression { env.TEST_RESULT == 'SUCCESS' }
      }
      steps {
        echo 'Deploying application because tests passed'
      }
    }
  }
}

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

The when block in the Deploy stage uses an expression condition to check if the tests passed by evaluating the environment variable TEST_RESULT. The Deploy stage runs only if this condition is true.

Commands

This command updates the Jenkins job configuration with the Jenkinsfile containing conditional deployment logic.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully

This command triggers the Jenkins pipeline named 'my-pipeline' to start the build, test, and conditional deploy stages.

Terminal

jenkins-cli build my-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] stage

[Pipeline] { (Build)

[Pipeline] echo

Building the application

[Pipeline] }

[Pipeline] stage

[Pipeline] { (Test)

[Pipeline] echo

Running tests

[Pipeline] script

[Pipeline] }

[Pipeline] stage

[Pipeline] { (Deploy)

[Pipeline] echo

Deploying application because tests passed

[Pipeline] }

[Pipeline] End of Pipeline

Finished: SUCCESS

This command fetches the console output of the last run of the 'my-pipeline' job to verify the conditional deployment executed.

Terminal

jenkins-cli console my-pipeline

Expected Output

Building the application

Running tests

Deploying application because tests passed

Key Concept

If you remember nothing else from this pattern, remember: Jenkins 'when' blocks let you run pipeline stages only when specific conditions are true.

Common Mistakes

Not setting or exporting the environment variable used in the 'when' condition.

The 'when' expression will always evaluate to false or error, so the deployment stage never runs.

Set the environment variable inside a 'script' block before the 'when' condition is evaluated.

Using 'when' conditions with syntax errors or unsupported expressions.

Jenkins pipeline will fail to parse or run the pipeline, causing build errors.

Use valid Groovy expressions inside 'when { expression { ... } }' and test them carefully.

Summary

Define deployment conditions inside the 'when' block of a Jenkins pipeline stage.

Use environment variables or Groovy expressions to control if deployment runs.

Trigger the pipeline and check console output to confirm conditional deployment.