Skip to end of metadata
Go to start of metadata

Plan branches are used to represent a branch in your version control repository, with the plan branch using the same build configuration as your plan.

Tools such as Git and Mercurial encourage a practice called feature branching, where a developer can use a new branch to work in isolation from his or her team members before merging their changes back into main line development. Previously however, changes made on a branch may not have been built and tested by Bamboo unless the developer had specifically set up a new build plan, or had cloned an existing plan and configured it to build the new branch.

Now, with plan branches in Bamboo:

  • Any new branch created in the repository can be automatically built and tested using the same build configuration as that of the parent plan. 
  • You have the flexibility to individually configure branch plans, by overriding the parent plan, if required.
  • Optionally, changes from the feature branch can be automatically merged back to the "master" (e.g. trunk, default or mainline branch) when the build succeeds.

On this page:

Activating plan branching

When you activate plan branching, Bamboo automatically creates plan branches whenever the source repo is branched. You can also create a plan branch manually.

You can override the master plan's configuration in a branch plan, if required.

To see a list of branches for a plan, click on the branch icon beside a plan name on the All Plans tab of the dashboard. Select a branch name from the list to go directly to the summary page for that branch plan.

Screenshot: The Plan Summary page for a branch, showing the 'branches' menu.

Auto branching

You can use auto branching for Git, Mercurial and Subversion repositories. For other repository types, you can use manual branching.

To have Bamboo automatically manage plan branches whenever the repo branches:

  1. Go to the Branches tab in the configuration pages for the plan you wish to branch.
  2. Check Create plan branches for branches detected in the repository.
  3. Enter a regular expression to match the repository branch names for which plan branches will be created. An example is: (branch1|branch2|branch3)/.* See the Java documentation on regular expressions.
  4. Make the following optional settings as required. These will be applied to all branch plans created from this plan configuration, although they can be overridden in those branch plans, if required.

    Not available for Subversion.
    Check Branch merging enabled, and complete either the 'Branch updater' or 'Gatekeeper' sections, as described below.
    JIRA feature branchesCheck Create remote links from JIRA issues... to have the plan branch automatically linked, using an issue key in the branch name. Described below.
    NotificationsDescribed below.
    Plan branch cleanupEdit the Remove after value (days), after which branches are automatically deleted, if no commits have been made to the VCS branch in that period. A value of zero prevents plans from being deleted.
    Branches Root

    Only available for plans that use a Subversion source repository. Bamboo assumes that your Subversion repository structure follows the convention for branches, and automatically calculates the branch root URL.

    For example, for the fastBuild repo with this URL:, Bamboo will expect that branches will be created at this location:

    If your Subversion repository structure follows a different convention, you can specify where repository branches will be created by selecting Change branch root URL.

  5. Click Save.

Branch detection

Once plan branching is enabled, Bamboo will check for a new branch every 300 seconds, by default. You can customize the branch detection interval as follows:

  1. Click the  icon in the Bamboo header and choose Overview.
  2. Click General configuration in the left navigation panel (under 'System').
  3. Enter a new value (in seconds) for Branch detection interval.
  4. Click Save.

Manual branching

Use manual branching for all supported repository types. You may want to consider using auto branching for Git, Mercurial and Subversion repositories.

To manually create a branch of a plan:

  1. Go to the Branches tab in the configuration pages for the plan you wish to branch.
  2. Click Create Branch. Bamboo automatically checks for branches in the specified repository for the plan.
  3. Select from the available VCS branches, then click Create.
  4. You can override the default settings for the branch, such as the source repository used, if you wish.

Integrating branches with JIRA

When a developer begins working on a feature described in a JIRA issue, they use Git or Mercurial to branch the repository. If they use the issue key as part of the VCS branch name, Bamboo will detect the issue key and automatically link the new branch to the issue:

  • The JIRA issue key needs to be in the name of the branch – 'jb-BDEV-790' and 'BDEV-769 1' are valid forms.
  • The link shows up right under the breadcrumb on the Build Result Summary for the plan branch, and on the JIRA issue too.

To use JIRA Feature Branching, Bamboo needs an application link to the JIRA server.


Branch notifications

You can get build notifications from branch plans just as you do for master plans.

To specify how notifications are sent by all branches created from a plan, go to the Branches tab for the plan's configuration and choose one of the following options:

  • Notify committers and people who have favourited this branch.
  • Use the plan's notification settings.
  • Notifications should not be sent for this branch.

You can override how notifications are sent from a particular branch plan, if necessary, by going to the Notifications tab on the Plan Branch configuration.

See Configuring notifications for a plan and its jobs for information about plan notifications.

Branch dependencies

You can use build dependencies for plan branches in a similar way to that for plans: a branch plan is triggered only when another branch plan has been successfully built. This can be used to ensure that breaking source code changes associated with one branch plan are detected before they can break the build of a dependent branch plan. Dependencies between master plans are maintained if their branch plans have the same name. See Setting up plan build dependencies for further information about dependencies.

Select Enable dependencies for all branches of this plan, on the Dependencies tab for the plan configuration, if you want plan branches to honour the build dependencies of their respective master plans.

Configuring plan branches

Whether a plan branch is created automatically or manually, the master plan maintains the structure and configuration of it's branch plans. However, you can go to the configuration pages to override the following settings in a branch plan:

Branch clean-up

On the Branch details tab of the branch's configuration, you can specify that a plan branch is not cleaned up automatically.

(info) Please note that automatic branch clean-up is supported for Mercurial, Git (Bamboo 4.1.1 and above) and Subversion (Bamboo 4.2.0 and above).

Trigger type

On the Branch details tab of the branch's configuration. See Triggering builds.

Note that you can only configure one trigger for a plan branch, and that this overrides all triggers that may be configured for the master plan.

On the Branch details tab of the branch's configuration. Described below.
Source repositoryOn the Source repository tab of the branch's configuration. See Linking to source code repositories.

On the Notifications tab of the branch's configuration. The options are:

  • Notify committers and people who have favourited this branch.
  • Use the plan's notification settings.
  • Notifications should not be sent for this branch.

See Configuring notifications for a plan and its jobs for information about plan notifications.

VariablesOn the Variables tab of the branch's configuration. See Defining plan variables.

Using automatic merging

Bamboo provides 2 merging models if you choose to automate your branch merging:

  • Branch Updater — a branch repo is kept up-to-date with changes to master.
  • Gatekeeper — the default repo is only updated with changes in the branch that have built successfully.

The automatic branch merge strategy for the master plan can be overridden in an individual plan branch, if required.


Branch updater

When to use

The Branch Updater should be used when you want to:

  • Automatically merge from the team's master branch to your feature branch before building the feature branch. Optionally, merge back into master if the build was successful.
  • Get notified when the changes on your feature branch are no longer compatible with the team's master branch.


To have recent changes in another repo merged into your branch repo:

  1. Go to the Branch Details tab of the branch plan's configuration pages.
    (Click on the branch icon beside a plan name on the All Plans tab, then choose Actions > Configure Branch.)
  2. Under 'Merging' select Branch Merging Enabled, and then click Branch Updater.
  3. Use the Merge From list to choose the repo from which changes should be merged with your feature branch.
  4. Select Push on only if you want those changes merged back into your branch once the build completes successfully,
  5. Click Save.


When to use

The Gatekeeper should be used when you want to:

  • Automatically merge your feature branch back into the team's master branch, after a successful build of the merged changes from both branches.
  • Get notified when a build of combined changes from both branches fails, preventing the feature branch from being merged back into the team's master branch.


To have your successfully built changes pushed to another repo:

  1. Go to the Branch Details tab of the branch plan's configuration pages.
    (Click on the branch icon beside a plan name on the All Plans tab, then choose Actions > Configure Branch.)
  2. Under 'Merging' select Branch Merging Enabled, and then click Gate Keeper.
  3. Use the Checkout list to choose the repo with which to merge your changes (and to which changes should be pushed).
  4. Select Push on only if you want your changes pushed to the other repo once the build completes successfully,
  5. Click Save.

Limitations with plan branches

The following limitations apply to using automated plan branching and merging:

Auto plan branching
  • Can only be used with Git, Mercurial and Subversion repositories. For other repository types, use manual branching.
  • Cannot be used with the Git implementation embedded in Bamboo. (You need to have set up native Git.)

Manual plan branching

  • Can be used for all repository types supported by Bamboo.
Auto branch merging
  • Can only be used with Git and Mercurial repositories.
  • Can only be used with branches that were configured in Bamboo.
  • Cannot be used with the Git implementation embedded in Bamboo. (You need to have set up native Git.)

Branches wallboard

The branches wallboard displays the status of all the branches and the plan that the branches belong to. The plan's own status always appears first. Plans shown as grey are disabled.

To display the branches wallboard:

  1. Go to the Plan Summary for the plan that has branches you want to display.
  2. Choose Actions > Branch Wallboard.

  • No labels


  1. Anonymous

    For the longest time we were trying to figure out what regex we needed to enter to get our branches pulled in. Figured I'd help others out.


    The above regex will work for (where ANYTHING can be any value):


    This is useful if you are using the git-flow feature in SourceTree or Git

    1. Thank you so much for this comment! Saved me a lot of time!

    2. Note that this regex is incomplete and also matches e.g. feature/

      You'll probably want (bugfix|feature|hotfix|release)/.+

    3. Thank you for this. It helped me work out how to best use git-flow with Bamboo in my testing. For those curious, I wrote all about it here:

      Bamboo and Git-flow by Example-ish

  2. Anonymous

    We have noticed that when we turn on automatic branch detection, and create a new branch, a duplicate of the new branch will be added to the plan each time the automatic branch detection runs (so every 5 minutes).

    We have just upgraded to Bamboo 4.4.0, and this didn't happen under our previous version (4.1.3). 

    Any idea what is going on?

    1. Hi there. I am really sorry that you are facing this issue. Please open a new ticket on, and in your support ticket please mention your current comment. This way we will know that you have been helped.

      Please reproduce the problem and provide your Bamboo logs and screenshots indicating the issue. We will investigate it, and in case there is a bug, we will try to fix it as fast as possible. Will talk to you on a support ticket.


      1. Is this what you meant? BAM-12789 - After Manually adding a branch, I see duplicate branches listed Resolved

      2. Anonymous

        OK, I'll raise a ticket. Thanks.

  3. When a new commit detected in a plan branch, Bamboo queues it for a build. What exactly remembered by Bamboo to checkout - branch names (as it is supposed to be) or explicit commits?

    The problem is following:

    - You have few branch plans configured as Gatekeepers for an integration branch (let's call it next).
    - Developer A pushes his changes into personal branch, Bamboo checkouts next, merges A's changes into it, and starts building it.
    - While it is building, Developer B does the same for his branch, and build B is queued.
    - After the plan A completes, Bamboo pushes updated integration branch (next) to Gitolite server.
    - Bamboo takes queued build B and checkouts integration branch (next) to do the same.

    The problem is that on that step Bamboo 4.4.0 checkouts not NEW state of the integration branch with just pushed changes, but that commit in the next which was last when the build B was queued. As result, it attempts to push back non fast-forward changes, and since they are disabled on Gitolite, the push fails. In fact, this makes impossible to use this feature because too many pushes fail if you have active committers.

    As I understand, it should checkout next by the branch name to its current state with just pushed updates, not an older commit (we configure branch by name, not a single commit). Then there will be no such problem since all commits into the integration branch will be fast-forward.

    Is this behavior by design? Any suggestions?

  4. Commenting my own comment: I think it's done this way to make possible to rerun the same build with the same data. But in that case we need an option for integration branch with automerge: should the HEAD at the time of queuing be remembered or Bamboo should fetch its actual state before merge and build...


  6. I configured plan branches to automatically manage branches that match release/.*

    That does create a plan branch for each new release (eg, release/1.0 release/1.1 ...)

    But it doesn't run the plan branch.

    Should I enable a trigger in the Plan Configuration (every 180 seconds)?

    But I don't want the parent plan to trigger, just the latest release.


  7. Is it possible to display the most recent or currently built branch status on the Build Dashboard for Plans with Plan Branches active?  For example, our default branch is 'develop', but actually that never gets built, instead we build branches called 'feature/x' or 'feature/y'.

    But this means that the Plan in the Dashboard always shows 'Never Built' even though we've built all of the other branches in there.  It also means that if a branch is being built, the 'In Progress' icon isn't displayed (again it's showing the 'Never Built' status of the 'develop' branch) so at a glance it looks like our build machine is not busy when in-fact it is.


  8. The problem I am having is that only the primary repository allows me to select a branch to build from. Would it be possible to enable branches on secondary repository branches when building?  For example our primary repo is our main source but we have a secondary repo for our shared jars. We have different branches for the jars repo. As of now I have to hard code the jar branch when I build. I would like to have a secondary branch(es) drop down(s) for any repos other than the primary repo that have branches enabled for that repo.


    1. Hi Patrick, I think your described feature is tracked here - BAM-11803 - Provide flexibility in choosing a repository while branching a plan Resolved .


  9. I am attempting to implement a Plan Branch and Auto-merge strategy.

    Plan Branch: So far, I have Bamboo automatically detecting feature branches, and correctly triggering builds when a commit is made and pushed on that feature branch. So that is working.

    Auto-Merge: I have setup the Gate Keeper functionality (to merge & push the feature branch into the parent branch on successful completion of build)

    I see the "merge" as having completed successfully under "Build result summary > Branch Integration Details" Feature Branch commit xxxxx successfully merged with xxxxx (latest commit on Plan's branch)

    Issue: When I check the commits and branches on BitBucket however, I don't see the two branches as having been merged (the way they would be had I selected to merge them manually) 

    Does this process not actually run the merge process? Just test the result? And it's up to the developer to run the ACTUAL merge?

    1. You should see the merge details on the result page but at the moment the merge commit does not show in Commits.

      1. So the commit has taken place? I don't see any commit / commit message?

        1. Can you see the commit in the git log? If not, be sure that you've checked  in your merge configuration.

  10. I've added some screen captures, I actually maybe correct (and I just didn't realize the merge'd commits were rebased) onto my parent branch:

    1. I spoke with our engineers and we use a fast forward merge, which does not leave a merge commit. 

  11. Thank you James, this makes sense. I appreciate the support!

  12. Hi James,

    We've had a lot of success using the "Branch Updater" method (rather than Gatekeeper) the merge-commits are kicking in and automatically merging our base-branch into our feature branches on each push (very cool!) However, it's working too well... when we process a pull-request and merge the commit via the BitBucket UI, and check the "close branch" the closing commit is also being pushed back against the feature branch (thus reopening closed branches) 

    We have to manually close the branch again.

    Is there a particular place we should close the branch in the UI to avoid this? I see 3 possible locations that we might be misconfiguring:

    1. Developer submits pull-request and checks ("Close Feature Branch") when submitting the pull request
    2. The merging developer chooses to "Close Feature Branch"
    3. The developer closes the branch in SourceTree and pushes the change (This is the only one that isn't triggering this repeat...and only if the branch as alreadybeen merged in the ui)

    For reference I have a screen shot here:


  13. Anonymous

    I have noticed that when I configure a plan branch with a automatic merging strategy set to 'Branch updater' and 'Push on' set, the commit & push did not take place at the end of a successfull build if a stage is disabled. In fact I have a stage to deploy maven artifiacts to a maven proxy and I don't want to enable it until delivery time, so I disabled the stage. I'm working with Bamboo 5.0, is it a issue ? I have a workaround which is to enable the stage and disable the 'maven task' in the stage's job but I have to add a useless script task of doing a 'Hello world' to have the stage return a successfull. Is there a better way to configure my plan ?

  14. Anonymous

    Concerning previous automatic push on issue, the real problem is when the disabled stage is set to be manual. In that case, the push on did not take place at the end of a successfull build. If stage is not manual, it's Ok.

  15. How can I get the name of the plan branch in a shell script task?

    In my case the plan has no repository.

    For plans with repo I use ${} to get the name of the repository branch.
    But I didn't find any variable to get the name of the plan branch.

     I have looked here
    but there's no plan branch name variable.

    bamboo.planName does contain branch after a dash, for example "My Plan - uat" or "My Plan - Snapshot - uat".
    It looks like I could parse it from there, but I believe there should be more clear way to do that. 


    1. I have this same question so will talk to the Bamboo dev team and post an answer here soon...

    2. Hi,

      Try "bamboo.shortPlanName" instead.



  16. Anonymous

    Is it possible at all to build GitHub's pull requests? How does bamboo fetch available branches? Is it something like 'git ls-remote --heads'?

    I would really love to be able to build branches matching 'refs/pull/.*/head', but I can not figure out how to make it possible (sad)

    1. Hi,

      Currently it's not possible to build GitHub pull requests, however we do have an open issue to develop this feature in the future.



      1. Hi

        Thanks for quick response. Do you mean this issue? It's kind of older than a year (smile)

        I'm just curious how does Bamboo fetch list of branches, and is there a way to change it?


        1. We periodically query the repository for new branches by fetching a local copy of the repo and comparing it against a list of previously detected branches. There isn't a good way to change that behaviour today but you can create plan branches via our Java API.

          Question about pull requests - do you wish to build forks?

          1. No, we don't use forks, we just open pull requests from our feature branches in the same repo for the sake of code review. By the way, doing something like `git ls-remote` would be a little bit more reliable, as it returns all existing branches.

  17. In the article is unclear, what event triggers a process of branch merging? Now I have understanding, that changes to the master branch does not automatically trigger Branch updater strategy on the feature branch. So, if you want to get fresh code from master to your feature, you need to kick a build of feature branch to start Branch updater. Not so automatic, isn't it?

    1. Yes I find this confusing as well, the documentation says the Branch Updater

      Automatically merge changes from the team's master branch into your feature branch, after a successful build of the master branch.

      but no build is triggered after a successful build of the master branch, after setting it up as described in this document. How do you set it up so a build is triggered on the feature branch after a successful build of the master branch?

  18. Unable to create plan branch for plan: IR360-D1D, branch: VCS Branch [release/REC_2.9.9].

    You can not create new branch, it has 1 jobs but your license only allows 0 more plans.

    Why creating branch is connected witg jobs? I though that job unit is for processing stages jobs.

    Anyway, once I had auto-resolves a plenty of subbranches of my master branch. This was correct?

    Maybe its bug?

    Furthermore if it is correct limitation, I will have job per subbranch decremented?

    1. I met the same error in Bamboo Cloud. It IS a license problem that I had starter license which only allows me to create maximum 10 jobs and 1 remote agent across the instance. For Bamboo Cloud, it is not possible to change license level to next tier (I tried to adjust elastic agents number in configuration but no effect). I got my Bamboo Cloud license upgraded to another tier with unlimited jobs + 1 agent by raising a support ticket to Atlassian.

  19. Where do you find this trigger, its no where to be found under the dependencies tab? Is this doc up to date?

    Select Trigger Dependencies for Branches, on the Dependencies tab for the plan configuration, if you want plan branches to honour the build dependencies of their respective master plans.


    1. Paul, this setting is now labelled as 'Enable dependencies for all branches of this plan'.

      Sorry for the confusion. I've updated this page.

  20. Never tried setting up branch merging before.  Reading this, it looks like the configuration examples under Branch updater and Gatekeeper could be swapped.  I see there are images already attached to this page which add credence to this.  For anyone else who may have been confused...

  21. I'm looking to achieve this with my git/stash branches and bamboo

    -- Create an auto-branch enabled plan ( done, this works well, newly create branches get run through CI automagically)

    -- Change the commands that I pass to our gradle build script inside a plan depending on what branch is running:.  different behaviors for master, release, and all other branches (feature/update/bug-fix etc).  Is there a way to run an extra build step, or stage depending on the branch.  Or perhaps I could dynamically determine the branch type and set environment vars to switch on?

  22. Does the 'gate-keeper branch build' have the same benefit with 'build on pull request created' feature which is missing currently in Bamboo/Bitbucket integration?

    From my understanding, people asks for 'build on pull request created' feature so you can make sure that after you merge the pull request from personal branch into main branch, it will not break the builds in main branch; With 'gate-keeper branch build' in bamboo, it will constantly do this check for every commits made in personal branch against main branch, IMO which is a bit of overkill comparing 'build on pull request created' feature request in bamboo.


  23. I've just discovered the reason I'm seeing duplicate plan branches appearing in Bamboo...


    LEGACY-93-apply-exclude-from-analysispor 1
    LEGACY-93-apply-exclude-from-analysispor 2 

    Weirdly, the previous versions were all disabled and only the last version is active, but only one branch exists in Bitbucket, named as per the first one in the list.

    This is because of a limitation in SourceTree which stops a developer from force pushing a local branch (after rebasing) back to the feature branch in the origin repo.

    The workaround our devs have been using is to delete the remote feature branch manually from SourceTree and re-push it, so there is only one branch in Bitbucket, but because it is technically a new branch, Bamboo pulls down a new instance of the branch (with  the name suffixed) and disables the old version.

    Even more redundant plan branches to clear up manually in Bamboo... aaargh!


  24. Our bamboo setup uses a database to back the unit tests,  if there is a check-in to default and other branches, will Bamboo attempt to build all in parallel, or are branched builds executed in serial?  If its parallel, maybe a feature would be the ability to configure such that default blocks branch builds and branch builds are queued for execution.