Branch-specific pipeline behavior in Jenkins - Commands & Configuration

Introduction

Sometimes you want your Jenkins pipeline to do different things depending on which branch of your code you are working on. This helps you test new features safely or deploy only from the main branch.

When you want to run tests only on feature branches but deploy only from the main branch.

When you want to build a different version of your app for development and production branches.

When you want to skip certain steps like deployment on pull request branches.

When you want to notify different teams depending on the branch being built.

When you want to run security scans only on release branches.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo "Building on branch ${env.BRANCH_NAME}"
      }
    }
    stage('Test') {
      when {
        anyOf {
          branch 'feature/*'
          branch 'develop'
        }
      }
      steps {
        echo 'Running tests on feature or develop branches'
      }
    }
    stage('Deploy') {
      when {
        branch 'main'
      }
      steps {
        echo 'Deploying from main branch'
      }
    }
  }
}

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

The when condition controls which branches run each stage:

• Test runs only on branches named like feature/* or develop.
• Deploy runs only on the main branch.

This lets you customize pipeline behavior based on the branch name.

Commands

Create and switch to a new feature branch named 'feature/new-ui' to simulate working on a feature.

Terminal

git checkout -b feature/new-ui

Expected Output

Switched to a new branch 'feature/new-ui'

Push the new feature branch to the remote repository so Jenkins can detect it and run the pipeline.

Terminal

git push origin feature/new-ui

Expected Output

Enumerating objects: 3, done.

Counting objects: 100% (3/3), done.

Writing objects: 100% (3/3), 250 bytes | 250.00 KiB/s, done.

Total 3 (delta 0), reused 0 (delta 0), pack-reused 0

remote: 

remote: Create a pull request for 'feature/new-ui' on GitHub by visiting:

remote:      https://github.com/example/repo/pull/new/feature/new-ui

remote: 

To https://github.com/example/repo.git

 * [new branch]      feature/new-ui -> feature/new-ui

Trigger the Jenkins pipeline manually for the 'feature/new-ui' branch to see branch-specific behavior.

Terminal

jenkins build example-pipeline -p BRANCH_NAME=feature/new-ui

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Building on branch feature/new-ui

[Pipeline] echo

Running tests on feature or develop branches

[Pipeline] End of Pipeline

→

-p BRANCH_NAME=feature/new-ui - Sets the branch name environment variable for the pipeline

Trigger the Jenkins pipeline manually for the 'main' branch to see the deploy stage run.

Terminal

jenkins build example-pipeline -p BRANCH_NAME=main

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Building on branch main

[Pipeline] echo

Deploying from main branch

[Pipeline] End of Pipeline

→

-p BRANCH_NAME=main - Sets the branch name environment variable for the pipeline

Key Concept

If you remember nothing else from this pattern, remember: use the 'when' directive in Jenkins pipelines to run different steps based on the branch name.

Common Mistakes

Not setting the BRANCH_NAME environment variable when testing locally.

The pipeline uses BRANCH_NAME to decide which stages to run, so missing it causes all stages to run or fail conditions.

Always set BRANCH_NAME when triggering the pipeline manually or in scripts.

Using exact branch names without wildcards for feature branches.

Feature branches often have different names, so exact matches miss many branches.

Use wildcard patterns like 'feature/*' to match all feature branches.

Placing 'when' conditions inside 'steps' instead of at the stage level.

'when' only works at the stage level and will be ignored or cause errors if used inside steps.

Always put 'when' directly under the stage, not inside steps.

Summary

Use the 'when' directive in Jenkinsfile stages to control execution based on branch names.

Test stages can run on feature or develop branches using wildcard branch patterns.

Deploy stages should run only on the main branch to avoid accidental deployments.