Multi-branch Pipeline

Created by Tass Skoudros, Modified on Fri, 11 Nov 2022 at 09:48 AM by Tass Skoudros

Multibranch Pipeline is one of the Pipeline project type in Jenkins 2.0 with Automated building and configuration capabilities.

Dependent Plugins:

  • Branch API (required)
  • Pipeline: API (required)
  • Pipeline: Job (required)
  • Pipeline: SCM Step (required)
  • Pipeline: Step API (required)
  • Pipeline: Supporting APIs (required)
  • Pipeline: Groovy (required)
  • Folders (required)
  • SCM API (required)
  • Script Security (required)
  • Structs (required)
  • JAXB (implied)


  • This Project type can be integrated with any of popular version controlling systems like Subversion, Github Organization Projects, Bitbucket Team Projects & Microsoft Team Foundation Server.
  • The primary feature of this type of project is that Jenkins can automatically manage and build branches of projects managed in a source control management system if it recognises them as Jenkins projects. It can also create new Pipeline projects for each branch it detects in the source control repository.
  • Supports scanning of SCM with customised poll frequency. Creating and automatically building the jobs is possible by using the presence of a Jenkinsfile as a marker and utilising a scanning process known as branch indexing.
  • For Pull Requests - It does a local merge of source and destination branches and then runs the tests off of that to simulate what the build would look like with your feature merged into destination branch. This provides an ability to setup Preview environments to also preview the changes before merging.
  • Provides an ability to manage the lifecycle of Orphan branches.
  • Declarative checkouts provides the power of super-fast source code clone on to the Jenkins Agents.
  • Flexibility to choose custom Pipeline Definitions and custom shared libraries for the entire project.


Click new item in Jenkins old UI (or) new pipeline in blue ocean interface. When you create a new Multibranch Pipeline project, you will typically point the job to an SCM repository instead of to a specific branch of a project. Below screenshot shows an example of the configuration screen for this type of project.

Branch Source Settings:

The first few settings here are pretty standard. However, notice that in the Behaviors section under Branch Sources, there is the default behaviour of "Discover branches." This is one of the key elements of a Multibranch Pipeline project: the ability to look into the SCM repository, figure out what branches are there, and set up jobs for them.
Other typical behaviours (as provided by the particular SCM plugin) can be added with the Add button. For Git, these might include, for example, ignoring branches based on regular expression and wild card patterns, specifying options when cloning, and cleaning out workspaces and much more.

Property Strategy Settings:

For Multibranch Pipeline projects, this is either "All branches get the same properties" or "Named branches get different properties." Selecting the latter allows you to specify one or more named branches (in a "Branch name" field) and choose a property to apply. Currently available properties are "Suppress SCM triggering" & "Pipeline branch speed/durability override".

  • Suppress SCM triggering will suppress the normal commit trigger for Jenkins in that branch.
  • Pipeline Branch speed/durability setting allows users to change the default durability mode for running Pipelines. In most cases this is a trade-off between performance and the ability for running pipelines to resume after unplanned Jenkins outages.

Configuration Section:

You will a couple of options by Jenkinsfile and Custom script.

  • Jenkinsfile - This is the functionality allows Jenkins to look for a file named Jenkinsfile in the root of the checked-out project to see if it can automatically build the branch of a project. While it is possible to change the path for the Jenkinsfile in the Script Path field underneath, it's best to just leave it as the default for standardization.
  • Custom Script – This allow you to embed the Jenkinsfile inline. Not recommended big projects

Scan Repository Triggers:

This can be set to "Periodically if not otherwise run" if desired. Basically, if set, this is a fallback in case one of the standard notification mechanisms (commit trigger, etc.) doesn't work. The
idea is that it allows to set a time interval here that specifies the longest period that you're willing to wait to check for changes if an event doesn't automatically trigger Jenkins. Check limitations section for more details

Remaining Settings:

The remaining sections on the configuration page are the same as the standard ones for a Folder project, such as "Health metrics," Pipeline Libraries, and Pipeline Model Definition allow multi-branch pipeline to have its own set of shared libraries just for the projects in the folder.

Branch indexing:

After initial configuration, Jenkins will run a "branch indexing" function to look for the presence of a Jenkinsfile in the branches of the project. If it finds a Jenkinsfile in any of the branches, it will automatically create a job for those branches and build them.

Below Screenshots describe that branch indexing is successful for couple of branches master and feature branch. Feature branch is disabled by branch indexing since there is active merge pull request from feature branch to master branch. PR checks in Github show the tests on Pull Request failed.

Current Limitations:

Source Code Management scanning is recommended only when Jenkins is behind a great firewall (i.e in People's Republic of China) where Github can't access Jenkins webhooks.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article