Multi-branch pipeline job creation in Jenkins - Commands & Configuration

Introduction

Managing multiple branches in a project can be complex. A multi-branch pipeline job in Jenkins automatically creates and runs pipelines for each branch, saving time and reducing manual setup.

When you have a project with many branches and want Jenkins to build each branch automatically.

When you want to test feature branches separately without creating jobs manually.

When you want to keep your CI/CD process organized by branch.

When you want Jenkins to detect new branches and run pipelines without extra configuration.

When you want to apply the same pipeline script to all branches in your repository.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building the project'
            }
        }
        stage('Test') {
            steps {
                echo 'Running tests'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying application'
            }
        }
    }
}

This Jenkinsfile defines a simple pipeline with three stages: Build, Test, and Deploy. It runs on any available agent. This file should be placed in the root of each branch so Jenkins can run the same pipeline for all branches automatically.

Commands

This command creates a new multi-branch pipeline job named 'example-multibranch' in Jenkins, pointing to the specified Git repository URL. Jenkins will scan all branches and run pipelines based on the Jenkinsfile in each branch.

Terminal

jenkins-jobs create-multibranch-pipeline --name example-multibranch --git-url https://github.com/example-user/example-repo.git

Expected Output

Created multi-branch pipeline job 'example-multibranch' pointing to https://github.com/example-user/example-repo.git

→

--name - Specifies the name of the multi-branch pipeline job

→

--git-url - Specifies the Git repository URL to scan for branches

This command tells Jenkins to scan the 'example-multibranch' job for branches and create pipeline runs for each branch found.

Terminal

jenkins-jobs scan-multibranch example-multibranch

Expected Output

Scanning multi-branch pipeline job 'example-multibranch' for branches...

Found branches: main, feature-1, bugfix-2

Triggering builds for new branches...

This command lists the builds triggered by the multi-branch pipeline job, showing the status of each branch's pipeline run.

Terminal

jenkins-jobs list-builds example-multibranch

Expected Output

Branch: main - SUCCESS

Branch: feature-1 - RUNNING

Branch: bugfix-2 - SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: a multi-branch pipeline job automatically detects and runs pipelines for all branches using the Jenkinsfile in each branch.

Common Mistakes

Not placing a Jenkinsfile in each branch

Jenkins cannot run a pipeline for branches without a Jenkinsfile, so those branches will be skipped.

Ensure every branch has a Jenkinsfile at the root with the pipeline definition.

Using incorrect Git repository URL when creating the job

Jenkins will fail to scan branches if the URL is wrong or inaccessible.

Double-check the Git URL and ensure Jenkins has access permissions.

Not scanning the multi-branch job after creation

Without scanning, Jenkins will not detect new branches or trigger builds.

Run the scan command or configure automatic branch indexing in Jenkins.

Summary

Create a multi-branch pipeline job pointing to your Git repository to manage all branches automatically.

Place a Jenkinsfile in each branch to define the pipeline steps.

Scan the multi-branch job to detect branches and trigger builds.

Check build status for each branch to monitor pipeline runs.