Jenkinsfile per branch - Commands & Configuration

Introduction

When working with multiple branches in a project, you may want each branch to have its own build and deployment steps. Using a Jenkinsfile per branch lets you customize the pipeline for each branch separately, so changes in one branch do not affect others.

When you want to test new features with different build steps before merging to main.

When different branches require different deployment environments or servers.

When you want to experiment with pipeline changes without impacting the main branch.

When you maintain long-lived branches with unique release processes.

When you want to keep branch-specific configurations close to the code.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    if (env.BRANCH_NAME == 'main') {
                        echo 'Building main branch with production settings'
                        // Add main branch build steps here
                    } else if (env.BRANCH_NAME == 'develop') {
                        echo 'Building develop branch with staging settings'
                        // Add develop branch build steps here
                    } else {
                        echo "Building feature branch: ${env.BRANCH_NAME} with default settings"
                        // Add feature branch build steps here
                    }
                }
            }
        }
        stage('Test') {
            steps {
                echo 'Running tests'
                // Add test steps here
            }
        }
        stage('Deploy') {
            steps {
                script {
                    if (env.BRANCH_NAME == 'main') {
                        echo 'Deploying to production'
                        // Add production deploy steps
                    } else if (env.BRANCH_NAME == 'develop') {
                        echo 'Deploying to staging'
                        // Add staging deploy steps
                    } else {
                        echo 'Skipping deploy for feature branch'
                    }
                }
            }
        }
    }
}

This Jenkinsfile uses the env.BRANCH_NAME variable to detect the current branch. It runs different build and deploy steps depending on whether the branch is main, develop, or any other feature branch. This way, each branch can have its own pipeline logic inside a single Jenkinsfile.

Commands

Create and switch to the 'develop' branch to test branch-specific Jenkinsfile behavior.

Terminal

git checkout -b develop

Expected Output

Switched to a new branch 'develop'

Push the 'develop' branch to the remote repository so Jenkins can detect it and run the pipeline.

Terminal

git push origin develop

Expected Output

Enumerating objects: 5, done.

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

Delta compression using up to 8 threads

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

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

Total 3 (delta 2), reused 0 (delta 0)

remote: 

remote: Create a pull request for 'develop' on GitHub by visiting:

remote:      https://github.com/example/repo/pull/new/develop

remote: 

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

 * [new branch]      develop -> develop

Trigger the Jenkins pipeline manually for the 'develop' branch to see branch-specific pipeline steps.

Terminal

jenkins-cli build my-pipeline -p BRANCH_NAME=develop

Expected Output

[Pipeline] Start of Pipeline

Building develop branch with staging settings

Running tests

Deploying to staging

[Pipeline] End of Pipeline

Finished: SUCCESS

→

-p BRANCH_NAME=develop - Specifies the branch name parameter to simulate branch-specific pipeline execution

Trigger the Jenkins pipeline for a feature branch to verify it uses the default build and skips deployment.

Terminal

jenkins-cli build my-pipeline -p BRANCH_NAME=feature/new-ui

Expected Output

[Pipeline] Start of Pipeline

Building feature branch: feature/new-ui with default settings

Running tests

Skipping deploy for feature branch

[Pipeline] End of Pipeline

Finished: SUCCESS

→

-p BRANCH_NAME=feature/new-ui - Simulates running the pipeline on a feature branch

Key Concept

If you remember nothing else from this pattern, remember: use the branch name variable inside a single Jenkinsfile to customize pipeline steps per branch.

Common Mistakes

Creating separate Jenkinsfiles in each branch without a shared base.

This causes duplication and makes maintenance harder because changes must be repeated in all files.

Use one Jenkinsfile with conditional logic based on the branch name to keep pipeline code centralized.

Not pushing the branch to the remote repository before Jenkins runs the pipeline.

Jenkins cannot detect or build branches that do not exist on the remote, so the pipeline won't run.

Always push new branches to the remote repository so Jenkins can trigger builds.

Using incorrect or missing environment variables like BRANCH_NAME in the Jenkinsfile.

The pipeline will not detect the branch correctly and may run wrong steps or fail.

Use the built-in Jenkins environment variable 'env.BRANCH_NAME' to get the current branch name reliably.

Summary

Use a single Jenkinsfile with conditional logic based on the branch name to customize pipeline steps.

Push branches to the remote repository so Jenkins can detect and build them.

Trigger builds with the correct branch context to verify branch-specific pipeline behavior.