Bitbucket's default behavior: most recently used repository

By default, Bitbucket selects the most recently used repository on the create branch page. Similarly, when linking Bitbucket projects to Jira projects, the most recently used repository of the configured project is selected.

App's default behavior: intelligent Jira project -> Bitbucket repository mapping

If you want a one-to-one relationship between Jira projects and Bitbucket repositories, Create Branch Wizard for Bitbucket selects the correct repository based on the issue keys it finds in the commit messages when you create a branch from JIRA.

This makes it possible to always have the right repository selected when coming from Jira's development panel and to prevent mistakes by creating branches in the wrong repository.

If you want to override this default behavior or want to make the create branch page settings dependent on other factors like the JIRA component of the issue, you can define so-called branch mappings.

Extend App's default behavior: use branch mappings

With branch mappings, you can configure for which JIRA project, component and issue type which branch name, branch type and branch from values should be filled in by the app when you create a new branch from JIRA.

Branch mappings can be configured for each repository under repository → settings → Create Branch Wizard:

You can configure multiple mappings with different JIRA projects for the same repository. If there are multiple branch mappings in different repositories, the most specific always wins.

E.g., if repo A has a mapping for JIRA project C and repo B has a mapping for JIRA project C and component C1, repo B is selected if a branch is created from a JIRA issue of project C and component C1 because it is more specific.

Example: branch mapping with custom branch names

The following screenshot shows an example of a branch mapping:

  • for JIRA issue type Sub-task, use custom branch naming with Jira variables in the template.
  • Branch From should be dev

When you now create a new branch from a Jira Sub-task issue, these values are set automatically in the Create branch dialog. Notice that the variables in the Branch Name Template got replaced by the actual values of the Jira issue: