Automatic branch merging

In order to use automatic branch merging, Bitbucket has to be able to determine the ordering of branches, and relies on semantic versioning of branch names. For example, Bitbucket will order these branch names like this: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. Read more about the Branch ordering algorithm, including some examples of branch ordering, later on this page. Bitbucket expects that the 'development' branch, typically the default branch, is always ahead of any 'release' branches. The final merge in the automatic cascade will be to the 'development' branch.

What happens if an automatic merge fails?

When an automatic merge fails, Bitbucket creates a new pull request for the failed merge, and the automatic merge operation stops. You should resolve the conflict locally before approving the new merge, which may start a new series of cascading merges. Note that a pull request that gets automatically opened when a merge fails won't trigger the continuation of the initial merge chain if resolved locally (which is the approach that we recommend).

There are a few reasons an automatic merge could fail:

• There could be a conflict detected that prevents the merge.

• There is already an open pull request with the same source and target that the automatic merge would close.

Enable automatic branch merging

You can enable automatic branch merging for all repositories in a project, and choose to inherit or override this setting in individual repositories. 

Enable automatic branch merging for all repositories in a project

All repositories in a project can inherit or override the branching model, including automatic branch merging. 

To enable automatic branch merging for all repositories in a project (requires project admin permission):

1. Go to Project settings > Branching model.
2. Select Enable automatic merging, then click Save.

Enable automatic branch merging for a single repository

To enable automatic branch merging for a single repository:

1. Go to Repository settings > Branching model.
2. Select Enable automatic merging, then click Save.

Branch ordering algorithm

Bitbucket is able to automatically merge changes to newer release branches, as long as Bitbucket can determine the ordering of those branches. Ordering is based on semantic versioning in the naming pattern for branches.

Bitbucket uses the following ordering algorithm to determine the branches in the merge chain:

• Branches are selected and ordered on the basis of the name of the branch that started the cascade (i.e. the target of the pull request for the merge).
• Branch names are split into tokens using any of these characters: underscore '_', hyphen  '-', plus '+', or period '.'.
• Only branches matching the name of the pull request target are added into the merge path. Matching means that every token before the first numeric token must be equal to the corresponding tokens of the target branch's name.
• Branches are ordered by number, if a given token is numeric. When comparing a numeric token with an ASCII token, the numeric is ranked higher (i.e. is considered as being a newer version).
• If both tokens are non-numeric, a simple ASCII comparison is used.
• In the unlikely case of the above algorithm resulting in equality of 2 branch names, a simple string comparison is performed on the whole branch name.
• There is a limit of 30 merges. 

Branch ordering examples

The table below provides examples of branch naming patterns that Bitbucket is able, and not able, to order correctly: