This is the documentation for Bamboo 5.8. View this page for the

Unknown macro: {spacejump}

of Bamboo, or visit the latest Bamboo documentation.

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.

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.

    Merging
    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: https://svn.mycompany.com/svn/fastBuild/trunk, Bamboo will expect that branches will be created at this location: https://svn.mycompany.com/svn/fastBuild/branches.

    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.

Merging
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.
Notifications

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.

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

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. 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:

ActionLimitations
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