Documentation for Bamboo 4.0.x. Documentation for earlier versions of Bamboo is available too.

Plan branches are used to represent a branch in your version control repository, where the plan branch uses 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. This guarantees that their new code functions correctly before sharing the changes with the rest of the team.

However, changes made on a branch may not be built and tested by Bamboo unless the developer sets up a new  build plan, or clones an existing plan that is configured to build the new branch. When using plan branches, any new branch that is created is automatically built and tested using the build configuration of the plan that plan branches was enabled for. Optionally, changes from the feature branch can be merged back to the "master" (e.g. trunk, default or mainline branch).

Note that you need to 'favourite' a plan branch in order to receive notifications about build results for it.

On this page:

Related pages:

Activating plan branching

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

Whichever way the plan branch is created, the default plan maintains the structure and configuration of it's branch plans. However, you can override the following settings in a branch plan:

  • the source repository, so that the branch uses a different repository from the default plan.
  • the plan variables, so that the branch uses different variables from the default plan.

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

You can click Detect Branches to get Bamboo to check for branches in the specified repository for the plan.

Auto branching

Use auto branching for Git and Mercurial repositories. For other repository types, use manual branching.

To have Bamboo automatically create a branch plan whenever the repo branches:

  1. Go to the Branches tab in the configuration pages for the plan you wish to branch.
  2. Select Enabled, under 'Automatic Branch Detection'.
  3. Enter a regular expression to specify the repo branch names for which plan branches will be created. See the Java documentation on regular expressions.
  4. Select Enabled, under 'Automatic Branch Clean-up', if required.
  5. Click Save.

(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).

 

Manual branching

Use manual branching for all supported repository types. You can use auto branching for Git and Mercurial 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.
  3. Select from the available VCS branches, then click Create.
  4. Select Override default's Repository in the Source Repository tab if you want the branch plan to use a different repository from the default plan. See Specifying the source repository and it's child pages for details.
  5. Click the Variables tab to override the plan variables of the default plan.

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

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 master repo is only updated with changes in the branch that have built successfully.

 

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.

Configuring

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. Select Branch Integration 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 only if you want those changes merged back into your branch once the build completes successfully,
  5. Click Save.

Gatekeeper

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.

Configuring

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. Select Branch Integration 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 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:

ActionLimitations
Auto plan branching
  • Can only be used with Git and Mercurial 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.)
Plan Branches with multiple repositoriesSee Is it possible to use plan branches to override the branch on multiple repositories in a plan? on Atlassian Answers.
  • No labels



Log a request with our support team.



Raise an issue for our developers.



See answers from the community.



Blog and update our documentation.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.