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. Select Automatically manage branches.
  3. Enter a regular expression to specify the repo 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.

    Remove after
    Edit the value, in 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.
    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.
    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. You may customize the branch detection interval:

  1. Click the  icon and select Overview.
  2. Click General Configuration in the left navigation panel
  3. Enter a new value in the Branch detection interval field
  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 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.

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 Specifying the source repository.

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 changes from the team's master branch into your feature branch, after a successful build of the master branch.
  • 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. 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 .


    1. Ooops, it looks like Oracle have changed their documentation. I've updated the link with the new page.

      Thanks for pointing this out.

  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. 


  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.