Child pages
  • Multi-Branch Project Plugin
Skip to end of metadata
Go to start of metadata


This plugin is deprecated. Please move to the Multibranch Pipeline job type.

This plugin adds additional project types that create sub-projects for each branch using a shared configuration.

Plugin Information

View Multi-Branch Project Plugin (DEPRECATED) on the plugin site for more information.


This plugin is deprecated. Please move to the Multibranch Pipeline job type.

Table of Contents


This plugin has evolved over the course of several releases, originally depending only on the SCM API Plugin, but has since adopted other APIs as they've become stable. The original goal was to provide a single new project type whose configuration mimics that of a standard free-style project. The only difference was that the SCM configuration section utilizes the SCM API Plugin (and so the options may seem somewhat limited compared to the usual SCM options). The project will use this SCM to automatically poll for a list of current branches and sync all the configuration to sub-projects. Each branch has its own sub-project. Sub-projects are just like normal projects, except they are automatically configured by the main (parent) project's page.

Screenshot - Project Page


Available SCMs

Any SCM plugin that has an implementation that extends the below class from the SCM API Plugin will be available:


Known implementations:


The environment variable BRANCH_NAME can be used to obtain – you guessed it – the branch name. It can be used in your scripts or in form fields that support variable expansion.




  • Branch names get encoded (i.e. a forward slash '/' becomes '%2F'), so some things may not work without additional configuration. The real branch names are stored in the sub-project's display name. Make sure both your container running Jenkins (ex: Tomcat, Glassfish, etc.) and any HTTP server acting as a remote proxy (ex: Apache, Nginx) are configured to support encoded slashes in the URL. The embedded Jetty container in jenkins.war can handle this by default.
  • Depending on the SCM implementation you're using, configuration options can be limited.
  • This project type should be compatible with plugins that you'd see in normal free-style projects, but compatibility can't be guaranteed.  Feel free to open an issue with your list of installed plugins, your configuration, and any relevant errors or logs.
  • Sub-projects appear to be configurable, but they will be overwritten by branch indexing if you manually modify them.  There is no clear way to remove or hide the configuration option on sub-projects (except maybe with project-based matrix authorization??), though version 0.1.x of this plugin accomplished that via some trickery that is not possible in newer versions.

Change Log

Version 0.7 (Apr 7, 2017)

  • Deprecated plugin
  • Removed migration-related code

Version 0.6 (Feb 22, 2017)

  • [JENKINS-41371][JENKINS-41867][JENKINS-41948] Fix compatibility issues with Branch API Plugin 2.0.x
    • Update core dependency to 1.642.3 (highest common denominator, matches Branch API Plugin)
  • [JENKINS-36896] Fix symlink path unsupported for Windows in migration code

Version 0.5.1 (Jul 8, 2016)

  • [JENKINS-36512] Fix case where config didn't apply to sub-project when user configured that sub-project directly
  • [JENKINS-36511] Fix config options for Matrix multi-branch (missing custom workspace and custom child workspace, extraneous JDK dropdown)
  • Add new item icons for Jenkins 2.x
  • Update new item descriptions
  • Also exclude workspaces from search for config.xml files during migration at startup
  • Further reduce unnecessary footprint for Job Configuration History

Version 0.5 (Jul 1, 2016)

  • [JENKINS-32234] Refactor to use MultiBranchProject API
    • Add Branch API Plugin as a dependency
    • Update core dependency to 1.625.1 (highest common denominator, matches Branch API Plugin)
    • Remove "Allow anonymous trigger of branch sync" setting
    • Remove "Suppress automatic build trigger after discovering new branches" setting
    • [JENKINS-32244] Provide environment variable for branch name
    • [JENKINS-32440] Fix issue with polling not being triggered (branch indexing now handles polling)
  • [JENKINS-36043] Fix NPE when saving configuration in Jenkins 2.9-2.11
  • [JENKINS-30089] Use BulkChange when updating sub-projects to prevent creating unnecessary job configuration history entries
  • [JENKINS-32255] Add Multi-configuration multi-branch project type (thanks to Alastair D'Silva)
  • Add Ivy multi-branch project type (thanks to Florian Bühlmann)
  • [JENKINS-33906] Add new icon to aggregate status of select jobs
  • [JENKINS-32322] Improve startup delay on large instances by ignoring 'archive' and 'builds' directories in migration code (thanks to Alastair D'Silva)
  • [JENKINS-34078] Remove use of deprecated JSR-305 annotations

Version 0.4.2 (Apr 16, 2016)

  • Move to Jenkins infrastructure
  • [JENKINS-34076] Fix broken branch syncing with Folders Plugin 5.5+
  • Revise BallColorFolderIcon to work with all Folder types

Version 0.4.1 (Dec 11, 2015)

  • Fix #128 (regression): Re-add ability to keep sub-projects disabled

Version 0.4 (Dec 2, 2015)

  • Fix #37: Add a option for triggering build for new branches (thanks to Hiroyuki Wada)
  • Update SCM API Plugin dependency to 1.0
  • Remove 0.1.x -> 0.2+ branch project migration code
  • Update Maven Plugin dependency to 2.12.1 (thanks to Robin Müller)
  • Use encoded branch names for both filesystem name and project name (real branch name set in display name)
    • Fix #23: View column links are broken for branch names with slashes
    • Fix #50: Using jenkins.model.Jenkins#getItemByFullName API with slashes in name does not work
    • Fix #76: Branches with slashes causing broken links in conjunction with other plugins
    • Fix #114: Unable to trigger downstream multi-branch jobs with slash in name
  • Refactor to use ComputedFolder API
    • Add Folders Plugin as a dependency
    • Update core dependency to 1.609.1 (highest common denominator, matches Folders Plugin)
    • Fix #44 (part 1): Unable to rename multi-branch projects
    • Fix #61: Jenkins GUI gets incredibly slow when saving a multi-branch project with many branches
    • Fix #94: Enable a project after restart not working
  • Fix #44 (part 2): Clone/copy template project when parent is copied

Version 0.3 (Aug 30, 2015)

  • Refactored AbstractMultiBranchProject to inherit from AbstractItem
    • Fix #85: Sync branches not working in Jenkins 1.621+
    • Fix #53: NPE with EmailExt plugin
  • Fix #89: Add new Maven Multi-Branch Project type
  • Fix #87: "Could not access hudson.model.JDK.DEFAULT_NAME" JellyTagException
  • Fix #54: Bubble build status up to host project view

Version 0.2.4 (Aug 5, 2015)

  • Fix JellyTagException on sync branches log in Jenkins 1.621+

Version 0.2.3 (Jul 7, 2015)

  • Fix issue with custom workspace configuration field in newer versions of Jenkins
  • Fix deadlocks (thanks to Greg Opaczewski)
  • Add some Japanese localization (thanks to mallowlabs)

Version 0.2.2 (Apr 14, 2015)

  • Fix exception on configuration page (No page found 'configure-branch-entries.jelly')

Version 0.2.1 (Apr 13, 2015)

  • Fix regression with ${JOB_URL}/syncBranches

Version 0.2 (Apr 13, 2015)

  • Heavy refactoring that abstracts much of the multi-branch functionality.
    • Set custom workspace now available
    • Template for sub-projects can now be configured via API at ${JOB_UR\L}/template/config.xml
  • Display warning on configuration page when no compatible SCMs are available.
  • Fixes exception java.lang.NoSuchMethodException: hudson.model.AbstractProject.convertUpstreamBuildTrigger(java.util.Set)

Version 0.1.3 (Oct 30, 2014)

  • Add ability to trigger branch sync via URL with option to allow it anonymously (thanks to Manuel Durán Aguete for the initial commit).

Version 0.1.2 (Aug 29, 2014)

  • Fix project-level permissions when using the "Project-based Matrix Authorization Strategy" security option.

Version 0.1.1 (Aug 13, 2014)

  • Fix configuration issue when restricting project runs to master.

Version 0.1 (Aug 12, 2014)

  • Initial Release

Upgrade Notes

Version 0.7.x

Removed migration-related code.

Upgrading from versions 0.1.x, 0.2.x, 0.3.x, or 0.4.x is not supported.

Version 0.6.x

See notes for version 0.5.x.

Version 0.5.x

Refactoring to depend on the Branch API Plugin required migration of config.xml in multi-branch projects and sub-projects for SCM settings and log rotator settings.

Upgrading from version 0.1.x or 0.2.x is not supported. Upgrade to version 0.3 and restart Jenkins before upgrading to the latest version.

Downgrading to version 0.1.x, 0.2.x, 0.3.x, or 0.4.x after upgrading is not supported.

Version 0.4.x

Refactoring to depend on the Folders Plugin required migration of config.xml in multi-branch projects for tracked disabled sub-projects, trigger spec for syncing branches, and project-based matrix authorization settings; and migration of config.xml in sub-projects for display name. Some migration required direct manipulation of config.xml in multi-branch projects.

Upgrading from version 0.1.x or 0.2.x is not supported. Upgrade to version 0.3 and restart Jenkins before upgrading to the latest version.

Downgrading to version 0.1.x, 0.2.x, or 0.3.x after upgrading is not supported.

Version 0.3.x

Significant refactoring in this version required migration of config.xml in multi-branch projects for the trigger spec for syncing branches.

Downgrading to version 0.1.x or 0.2.x after upgrading is not supported.

Version 0.2.x

Significant refactoring in this version required migration of config.xml in sub-projects and build.xml for each build in each sub-project. Migration required direct manipulation of these files.

Downgrading to version 0.1.x after upgrading is not supported.


  1. I like the idea here.  Some concerns or thoughts I'd have if we were to use this:

    1. We have so many branches.  Many are active, some are release branches, some are abandoned, but we do try to get rid of most branches.

    2. Would the workspace location be the same between sub-projects or would this be dynamic?  I was thinking that I may want to execute branch A and B builds at the same time.

    3. If the workspace location is the same, I'd be worried about wiping out my build server's available disk space quickly.  Today I use generic "branch" and "release" projects and a user picks the branch they want to build for using the SVN tag/branch parameter.  I do use the regex functionality to control the branch choices in those projects (so you can't build a release build in a branch project).  If I have 20 active project branches and our working copy+build artifacts are 3GB, that would mean 60GB of space could be consumed pretty quickly. With my current setup, we let the SVN switch functionality built-in switch the workspace to the right branch we need for the current build.  What I don't like about this is that I lose the change tracking functionality built into Jenkins.  My trunk projects do not lose this though, so I always have that.

    That's enough for now.  I guess I'd like to understand better what problem you are trying to solve.  What is the vision for this plugin?  I'm interested.  One reason I'm interested is the lack of templates in Jenkins.  I would really, really love Visual Studio-like Property Sheets in Jenkins, where a project can include as many property sheets as they want and then I can change a property sheet to update all of the projects using it.  That'd be wonderful.

    1. I'll try to answer some of your concerns

      1. The SCM API allows you to set include and exclude regexs for your branch names.  You can use this to try to limit sub-project creation to your active branches.

      2. Workspace location currently is non-configurable and unshared.  They reside in ${JENKINS_HOME}/jobs/your-multi-branch-project/branches/${branchNameEncoded}/workspace.  This allows builds to run concurrently for different branches.  Think of the sub-projects as normal projects, but their configuration is shared and their creation/deletion is handled by the parent project.

      3. Disk space is always a valid concern, but currently there's no way to combat those issues because as mentioned above the workspace is unshared.  You could try using an artifact repository to publish your artifacts and define a cleanup process there.  I believe there's another plugin to clean the workspace after a build, so that in combination with a separate repository may help you out.

      The main issue I'm attempting to solve is to offer a way to copy a job for each available branch -- automatically, and within the Jenkins UI.  Manually copying a job each time you get a new branch is tedious.  Manually editing each one when you need to make a change to your job's configuration is even more tedious.  I already accomplished the automatic part using the Jenkins API and a template project by writing a basic Java application.  I just wanted a more convenient way to do it and be able to share it in the plugin update center.  You mentioned the lack of templates in Jenkins OSS and this plugin is an attempt ease that pain at the project level by having a single shared configuration (the "template") for each sub-project.  Change one configuration, all sub-projects get updated.

      The vision?

      What I'm looking into right now is a way to better support different project types with the sub-project generation.  Right now it's just like a free-style project, but I'd also like to add Maven-style and matrix-style project types.  How exactly I'm going to accomplish that has yet to be determined -- just need some time to hack away at it.

      More options.  Specifically a retention policy for sub-projects whose branches get deleted.  Support for the custom workspace location setting.

      Get feedback and go from there.  The automation I do is just a small subset of the software development world.  Everyone has different needs, and I'll attempt to accommodate them where it makes sense and my time permits.

  2. Thanks, I'm using this plugin and it is working well except for branch names that have slashes in them.  Something like feature/newFeature (we are using GitFlow).  

    It looks like Jenkins is creating the subproject, and the builds are happening, but the link in jenkins to go look at the subproject or the build log just comes up blank.

      1. This does not work for me. I'm running Jenkins as java -jar, and it is using Jetty. Then it is fronted by Apache. When I go directly to Jenkins, it works, but Apache gives me a 404 when I go through Apache.

        If you are fronting it with Apache, look at which has some hints that might help.

  3. This option will be wonderful if added to svn repository with maven project type

    by other words if it added to default scm (svn) plugin to be available to any project type 

  4. I love this plugin, but there is one thing that really annoys me: the status and weather icon of the multibranch project, for the purpose I use it for, should be tied up to the status of the last built branch.

    Is it possible to do that?

    The reason is: in this project my team builds a new release every week, and jenkins is configured to pick up only "release*" and "master" branches, so the last one built is always the correct representation of the state of the project.

  5. I do like this plug-in.  We have a ton of branches and some stay active a long time.  My Question to anyone that can answer. 

    How can you make one Mutli-branch job call another. 

    here is what I am looking for: 

    We have branch job that runs but then I would like it to trigger another branch job and it doesn't appear you can just place the url in the Trigger Job plugin and make it work.

    Here is my branch job:  http://vm-jenkins:8080/jenkins/view/DLL%20Jobs/job/Ribbon.dll/branch/main%2Faddons%2FRibbon/   and I want that to run this job http://vm-jenkins:8080/jenkins/view/DLL%20Jobs/job/P21.Extension.dll/branch/main%2FExtensibility/  

    Thoughts? Suggestions?

  6. Very useful plugin. But unfortunately I can not use it for the following reason. The fact is that in our case, each branch built in different environments and have different commands to build and configuration. This plugin uses a forced synchronization that results in all configurations of the branches to a single species. 

    Is it possible to make a choice synchronization as a parameter on demand? Perhaps there are other ways to solve? Any ideas? I will be very grateful.


  7. HI , this is great plugin - I have 2 requests :

    1. I want to run our integration tests after every feature build - need to use the multi scm plugin to clone 2 git repositories -

    2. it would be great if the job generator plugin will support this type of projects -

    and again Thanks for a great work

  8. Please update the change log to include 0.4.2.

  9. -

    I know that the goal of this plugin is to share the same configuration between branches but is there a way to have per branch configuration and without overwriting them after a sync? An option for this purpose would be great.


  10. D S

    Please help. This plugin is crashing my production windows jenkins server. It has an issue on windows with symlinks.   It will not let me remove or disable it because there is a dependent called "environment script plugin"
    I use the environment script plugin so I am afraid to remove that. I could remove "environment script plugin" then remove "Multi-Branch plugin" and add back in the "environment script plugin" but I am worried it will break
    my heavily used production jenkins jobs. What is the best way to remove Multi-Branch plugin without breaking jobs or jenkins or removing other plugins. Is there a .jpi file and folder I can delete?  Please advise.
    Note answering this will greatly help a non profit company doing good in the world.  Thanks!!!!!!

  11. What does "DEPRECATED" mean?
    No more features? Or even no more bugfixes?
    Does a guide for switching to Multibranch-Pipeline Plugin exist?