Using plan branches

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.

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. 
  • Any branches deleted from the repository can be deleted automatically from Bamboo according to the settings.
  • 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.

Further reading:

1. Viewing plan branches

tip/resting Created with Sketch.

Use the Branch status page for quick access to plan branch information.

You can access the list of all branches in a plan from different places. For example, you can select the Branch iconBranch iconnext to the plan name in the Build dashboard view:

Branch view in the build dashboard

You can also access the branch list from the Plan summary view:

Branch view in the plan summary

2. General branches configuration

You can create plan branches manually or automatically. The branch configuration can be provided on the plan level and customized on the branch level . The settings provided in the branch configuration override the settings provided for the plan.

Automatic branch management

Plan branches can be created and deleted automatically based on the updates in the primary source repository. Automatic branch management is available for Git, Mercurial, and Subversion. For other repository types, you can use manual branching. You can override the default settings for a branch, such as values of the variables.

You can override the branch deletion settings in the branch details configuration view.

You can specify how often Bamboo checks the primary source repository for new or deleted branches in the general branch settings.


To hand over the branch management to Bamboo:

  1. In the Plan summary view, select Actions C onfigure plan.
  2. Select the Branches tab.
    1.  Configure the following:

      Primary source repository branches


      Manually

      Bamboo doesn't create new plan branches automatically. You can create branches manually.

      When a pull request is created

      Bamboo creates a plan branch automatically when a new pull request is created. If a pull request is merged or declined, Bamboo will disable this plan branch.

      You can select the Forked repositories are allowed option to enable Bamboo to detect pull requests originating from forked repositories.

      If forked repositories are not allowed, the source repository must match the target repository.

      This option is available for environments that support pull requests. Currently, these are Bitbucket Server, Bitbucket Cloud, and GitHub.

      If you're using Bamboo with Bitbucket Server, detecting pull requests from forks requires Bitbucket Server 7.20 or later and that you're connected to Bitbucket Server's primary mirror (secondary mirrors are not supported).

      Bitbucket Cloud public repositories are supported by default. To use this feature with a private repository, ensure that the owner of the target repository has access to its forks.

      To increase build safety, Bamboo will not create new plan branches from divergent branches in a forked repository. See Working with branch divergence.

      The build statuses of PRs from forked repositories won't appear in Bitbucket Data Center and Server, Bitbucket Cloud, or Github. To see the build results, go directly to Bamboo.

      When a new branch in the repository is created

      Bamboo creates a plan branch for each new branch detected in the primary source repository.

      When a new branch in the repository is created and matches the expression

      Bamboo creates a plan branch for each new branch detected in the primary source repository that matches the regular expression that you provided.
    2. Configure plan branch clean up:

      Primary source repository branches

      Description

      After a branch was deleted from the repository

      When a branch is deleted from the repository, Bamboo will wait for provided number of days before deleting the plan branch.

      After branch inactivity in repository

      When a branch is inactive for provided number of days, Bamboo will delete the plan branch.

      If a branch in the primary source repository is inactive, Bamboo does not automatically delete the corresponding plan branch.

      If you selected Clean up plan branch automatically in the configuration on the branch level , the branch is disabled and deleted according to the daily cleanup rules, regardless of the automatic branch management settings. Clean up plan branch automatically is selected by default for manually created plan branches .

  3. Select Save to apply the changes.


Global settings - branch detection interval

Once automatic plan branch management is enabled, Bamboo checks for new or deleted branches in the primary source code repository.

You can specify how often Bamboo checks for new branches in the primary source repository in the system settings. The default value is 300 seconds.


To configure the branch detection interval:
  1. Select  > System General configuration .
  2. In Global system configurations, set the branch detection interval. Provide the value in seconds, the default value is 300.

Manual branch management

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

To manually create a branch of a plan:

  1. In the Plan summary view, select Actions C onfigure plan .
  2. Select the Branches tab, then Create plan branch .
  3. In the Create plan branch view, you can create branches in one of the following ways:

    ActionDescription
    Select from available VCS branches

    Select one or more branches from the list of available VCS branches.

    At the bottom of the list of the branches you can select the Enable branches check box, which makes all selected branches available for building and change detection.

    Select Create plan branch manually to go to manual branch creation screen.

    Create plan branch manually

    Provide:

    • a display name (required) - overrides the VCS branch name
    • a branch description - a meaningful description of the branch
    • VCS branch name - the name of the branch in the VCS repository

    You can select the Enable branches check box, which makes the new branch available for building and change detection.

    Select Auto-detect VCS branches to go back to the list of available VCS branches.

  4. Select Create.

Automatic branch merging

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

  • Branch Updater — a branch repo is kept up-to-date with changes to master. Note that changes on your master branch do not trigger branch builds.
  • Gatekeeper — the default repo is only updated with changes in the branch that have built successfully.

Any updates are performed only if the merged branches have built successfully.


The automatic branch merge strategy for the master plan can be overridden in an individual plan branch, if required. Automatic branch merging is not available for Subversion.

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 and branch merge.
  • Get notified when the changes on your feature branch are no longer compatible with the team's master branch.


Change detection is available only for the branch you're currently working on.

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. 
    (Select the branch icon beside a plan name on the All build plans tab, then select the  icon.)
  2. Under Merging select Branch merging enabled, then Branch updater.
  3. Use the Merge from list to select 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. Select Save.

Branch updater

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. 
    (Select the branch icon beside a plan name on the All build plans tab, then select the  icon.)
  2. Under Merging select Branch merging enabled, then Gatekeeper.
  3. Use the Checkout list to select 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. Select Save.

Branch gatekeeper

Integrating branches with Jira applications

Check Create Remote Links from Jira Issues to have the plan branch automatically linked, using an issue key in the branch name. 

When a developer begins working on a feature described in a Jira application 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 application 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 issue too.

To use Jira applications Feature Branching, Bamboo needs an application link to the Jira application 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 favorited 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 triggers

You can configure how new plan branches should be triggered.

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

  • Same as defined in parent plan

  • None. Run new plan branches manually

  • Custom trigger

After choosing a Custom trigger you can pick any trigger type, that is normally available for the plan.

Branch triggers

You can overrider branch trigger for a particular branch by going to Branch details tab on the Plan branch configuration.

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.

See Triggering builds for more information about plan triggers.

Subversion branches location

This section is displayed only 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 Manually define branch detection path.

Repository branch detection options

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 in the Advanced options section on the  Dependencies  tab for the plan configuration, if you want plan branches to honor the build dependencies of their respective master plans.

3. Configuring a plan branch in Bamboo

Branch details configuration


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.


By default, plan branches are deleted automatically after:

  • 7 days after the branch was deleted in the primary source repository OR
  • 10 days of branch inactivity in the primary source repository 

The values can be specified on the plan level.

Trigger type

You can override the way that Bamboo triggers specific plan branch. You can choose any trigger type, that is normally available for the plan and any of the available trigger conditions:

  • Only run build if other plans are currently passing

  • Only build branches when there are changes

  • Only run plan when no child plans are queued or in progress

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

You can override automatic merging strategy for chosen plan branch. Available merging strategies are described above.

Branch repositories

Once the plan branch is created, automatically or manually, all repositories defined in the plan inherit settings from the master plan by default. The only exception is the default repository, which uses one of the following branches:

  • branch selected by you during the manual creation of the plan,

  • branch detected in VCS in case of automatically created plan.

You can change settings of all repositories defined in the plan branch in the Repositories tab. In this tab, simply put a desired branch name or enable the Change repository settings for this branch plan toggle if you need to modify more settings.

In the Branch details tab the Repository branches section gives you a quick overview of repositories and branches configured in the plan branch. The Default repository settings changed flag indicates that this repository overrides more settings from the parent plan. The No branch support flag means that a given repository type does not support branches.

Configuring plan repositories and branches

Changing the repositories configured in a plan affects all the existing branches and automatic branch detection. Keep in mind that:

  • removing a repository from a plan removes it from all plan branches
  • repositories added to the plan configuration are also added to all plan branches (the VCS branch configuration is inherited from the plan configuration unless you change it manually)
  • the automatic branch detection and expiry feature creates and removes branches according to the configuration of a plan's default repository

If you remove the default repository from the plan, Bamboo will try to restore the VCS branch for all existing plan branches. If the VCS branch does not exist in the new repository, the plan branch is marked as invalid and won't be built. In this case, you should manually correct the configured branch in the Repositories tab.

If you need to replace the the default plan repository, we strongly recommend that you set the replacement repository as the new default first, and only then remove the old default repository.

Notifications

You can override sent notification for builds for specific branch on the Notifications tab of the branch's configuration. The options are:

  • Notify committers and people who have favorited 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.

Variables

You can override values of plan and global variables at the Variables tab of the branch's configuration. See Defining plan variables.



Other

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. Select Actions > Branch wallboard.

Last modified on Jan 19, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.