Working with Multibranch Pipelines

1. Creating Multibranch Pipeline Job

Example: Create Multibranch Pipeline Job via UI

1. Go to Jenkins dashboard
2. Click "New Item"
3. Enter item name (e.g., "my-multibranch-pipeline")
4. Select "Multibranch Pipeline"
5. Click "OK"
6. Configure repository source (e.g., Git)
7. Set branch discovery strategy
8. Save and build

Field	Description	Example Value
Project Name	Name of the multibranch pipeline job	`my-multibranch-pipeline`
Repository URL	Source code repository URL (e.g., Git)	`https://github.com/example/repo.git`
Branch Discovery	How Jenkins identifies branches to build	`Scan repository periodically`

Note: Jenkins automatically scans for new branches and builds them when changes are detected, based on configured branch discovery strategies.

2. Configuring Branch Sources

Property	Value	Description
source	`git`	Specifies the version control system used for the branch sources.
credentialsId	`git-credentials`	ID of the credentials to use for accessing the repository.
remote	`https://github.com/example/repo.git`	URL of the remote Git repository.
includes	`feature/,release/`	Patterns to include branches (e.g., feature branches or release branches).
excludes	`test/*`	Patterns to exclude branches (e.g., test branches).

Example: Configuring Git Branch Source

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: Ensure that the credentialsId is correctly configured in Jenkins to allow access to the repository.

3. Using Branch Discovery Strategies

Strategy	Description	Usage	Notes
Scan Repository	Scans the repository for all branches and tags.	`Branch Source` → `Scan Repository`	Default strategy; includes all branches and tags.
Regular Expression	Uses a regex pattern to filter branches.	`Branch Source` → `Regular Expression`	Allows filtering branches by name using regex.
Scripted Pipeline	Uses a Groovy script to define branch discovery logic.	`Branch Source` → `Scripted Pipeline`	Advanced strategy for complex branch filtering logic.

Example: Regular Expression Strategy

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The Scan Repository strategy is the default and includes all branches and tags in the repository.

Warning: Using Scripted Pipeline strategies can introduce security risks if not properly validated.

4. Filtering Branches by Name

Option	Values	Description
Branch Name Filter	`feature/*`	Pattern to match branch names
Excluded Patterns	`release/*`	Patterns to exclude from triggering builds

Example: Configure Branch Name Filter

pipeline {
    agent any
    triggers {
        upstream(upstreamProjectNames: 'parent-job')
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The branch name filter uses regular expressions. Use * for wildcard matching.

Warning: Excluding branches like release/* prevents builds from running on those branches.

5. Configuring PR Discovery

Option	Values	Description
prDiscoveryStrategy	`github`, `gitlab`, `bitbucket`	Defines the platform for PR discovery (e.g., GitHub, GitLab)
prBranchName	`feature/.`, `fix/.`	Regex pattern to match PR branch names
prTrigger	`onPush`, `onPullRequest`	When to trigger pipeline execution (on push or PR creation)

Example: GitHub PR Discovery Configuration

pipeline {
    agent any
    triggers {
        upstream(upstreamProjectNames: 'main-pipeline')
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: Ensure that Jenkins has appropriate permissions to access the Git repository and read PR information.

6. Using Scan Triggers

Scan triggers in Jenkins Multibranch Pipelines control how and when Jenkins scans for new branches or changes to existing branches. These triggers are essential for keeping pipelines in sync with source control.

Trigger	Description	Configuration	Notes
SCM polling	Periodically polls the SCM for changes.	`pollSCM` with interval (e.g., `/5 * * *`)	Can be resource-intensive; use with caution in large repositories.
Webhook	Triggers pipeline on SCM events (e.g., push, PR creation).	`webhook` with `triggerOnPush` and `triggerOnPr`	Requires SCM plugin support (e.g., GitHub, GitLab).
Scheduled Scan	Scans branches at specific intervals.	`scanRepository` with cron expression	Useful for ensuring pipelines are up-to-date at regular intervals.

Example: Configure Webhook Trigger

pipeline {
    agent any
    triggers {
        upstream 'upstream-job-name'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: Webhook triggers require proper SCM setup and may need additional configuration in the source control system (e.g., GitHub Webhooks) to function correctly.

7. Managing Branch Properties

Property	Values	Description
branch.name	`main`	Name of the branch
branch.displayName	`main`	Display name of the branch in Jenkins UI
branch.properties	`["build-parameters", "git-branch"]`	Properties associated with the branch

Example: Setting branch properties via Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
    post {
        always {
            script {
                if (env.BRANCH_NAME == 'main') {
                    echo 'Main branch properties applied'
                }
            }
        }
    }
}

Note: Branch properties can be managed through the Jenkins UI or via a Jenkinsfile. These properties are used to configure specific behaviors for different branches.

8. Using Orphaned Item Strategy

The Orphaned Item Strategy in Jenkins Multibranch Pipelines determines what happens to branches and tags that are no longer present in the source control system. This strategy helps manage cleanup of obsolete items and ensures that only active branches and tags are processed by the pipeline.

Strategy	Description	Behavior	Notes
Discard Old Items	Removes old items that are no longer active in the source control system.	Deletes branches and tags that have been removed from the repository.	Default behavior in most setups.
Keep Only One Item	Retains only one item per branch or tag, discarding older versions.	Keeps the most recent version and deletes previous ones.	Useful for reducing clutter in the Jenkins UI.
Keep Items with Specific Labels	Retains items that match specific labels or criteria.	Allows selective retention of branches based on labels.	Requires configuration of labels in the source control system.

Example: Configuring Orphaned Item Strategy in Jenkins Pipeline

pipeline {
    agent any
    triggers {
        pollSCM 'H/5 * * * *'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

Note: Orphaned Item Strategy settings can be configured in the Jenkins UI under Manage Jenkins > Configure System or via the Jenkinsfile using the orphanedItemStrategy directive.

Warning: Misconfiguring the Orphaned Item Strategy can lead to loss of historical data or unexpected behavior in builds. Always test configurations in a development environment before applying them to production.

9. Configuring Build Strategies

Strategy	Description	Configuration	Notes
Build Periodically	Triggers a build at specified intervals	`H 2 * * *`	Uses cron syntax. NEW in Jenkins 2.375+
Build After Other Projects Are Built	Triggers a build after specified projects complete	`projectA, projectB`	Supports upstream/downstream dependencies
Poll SCM	Checks for changes in SCM at regular intervals	`H/5 * * * *`	Can be resource-intensive; use sparingly
Rebuild Previously Failed Builds	Automatically rebuilds builds that failed in previous runs	`true/false`	Can cause cascading failures if not managed carefully
Build When a Change Is Pushed to the Repository	Triggers builds on any SCM push event	`SCM polling`	Requires proper SCM configuration and permissions

Example: Build Periodically Configuration

pipeline {
    agent any
    triggers {
        upstream 'projectA'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: Build strategies can be combined, but care must be taken to avoid circular dependencies or excessive resource usage.

10. Using Branch Indexing

Branch indexing in Jenkins allows you to refresh the list of branches available in a multibranch pipeline. This is particularly useful when new branches are created or existing branches are deleted.

Command	Description	Notes
Build Now	Triggers a new build of the multibranch pipeline	Can be initiated from the Jenkins UI or via API
Scan Repository	Scans the repository for new or deleted branches	Can be scheduled or triggered manually

Example: Triggering a Branch Index Scan via Jenkins UI

1. Navigate to the multibranch pipeline project in Jenkins
2. Click on "Scan Repository" under the "Build Now" button
3. Wait for the scan to complete and observe new branches in the branch list

Note: The scan process can take time depending on the size of the repository and number of branches.

Warning: Frequent scans can lead to high resource usage. Consider scheduling scans during off-peak hours.