Using plan branches

Branch management

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.

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

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

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 Change subversion branches URL.

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.

By default, automatic branch management is:

• disabled for branches that you create manually
• enabled for branches that are created automatically

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

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

To hand over the branch management to Bamboo:

1. Go to the Plan Configuration view: in the Plan summary view, click the  Actions  button   and select Configure plan
2. Click the Branches tab.

3. In the  Automatic branch management  section, configure the following:

   Primary source repository branches	Action	Description	Comments
   New branches	Do not create plan branches (default)	Bamboo does not create new plan branches automatically when new branches are detected in the primary source repository.	Independently from the automatic branch management settings, you can always create branches manually.
   	Create plan branches for all new branches	Bamboo creates a plan branch for each new branch detected in the primary source repository.
   	Create plan branches for matching new branches	Bamboo creates a plan branch for each new branch detected in the primary source repository that matches the regular expression that you provided.
   Deleted branches	Do not delete plan branches (default)	If a branch in the primary source repository was deleted, 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".
   	Delete branches after a period of time	If a branch in the primary source repository was deleted, Bamboo deletes the corresponding plan branch. The value must be higher than 0 and is specified in days. Plan branches are deleted at most once a day.
   	Delete branches with a daily cleanup	If a branch in the primary source repository was deleted, the corresponding plan branch is removed with a daily cleanup that happens daily at 3 AM (server time).
   Inactive branches	Do not delete inactive plan branches (default)	If a branch in the primary source repository is inactive, Bamboo does not automatically delete the corresponding plan branch.
   	Delete plan branches after a period of inactivity	If a branch in the primary source repository is inactive, Bamboo deletes the corresponding plan branch if no commits are detected for the specified period. The value must be higher than 1 and is specified in days.

4. Click Save at the bottom of the view to apply the changes.

Global settings - branch detection interval

Once plan branching 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. Open the Bamboo Administration view by clicking the cog icon  and selecting a section from the list that opens.
2. In the Bamboo Administration view, scroll down the menu on the left to find the System section.
3. Click General configuration.
4. 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. Go to the Plan Configuration view: in the Plan summary view, click the Actions button  and select Configure plan
2. Click the Branches tab.
3. Click Create plan branch in the upper right of the view.

4. In the Create plan branch view, you can create branches in one of the following ways:

   Action	Description
   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.
   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. Click Auto-detect VCS branches to go back to the list of available VCS branches.

5. Click Save.

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 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 dependenciesfor further information about dependencies.

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

Branch details configuration

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: