Merge a pull request
You can merge a pull request or set a pull request to auto-merge even if you aren’t the author of this pull request. To do this, you need the write or admin permission for the repository that the pull request targets.
This flexibility allows different teams to have different approaches to using Bitbucket. If your team requires stricter control, consider using branch permissions to restrict who can merge a pull request to particular users or groups. You might also want to consider using a plugin to enforce a particular workflow, for example to ensure that only approvals from members of your review team allow merging, see the page Checks for merging pull requests.
If a pull request is a draft, it can’t be merged. Make sure all draft pull requests have been reviewed and approved before the merge.
Merge a pull request
To merge a pull request:
- In the top-right corner of the pull request view, select Merge.
- In the Merge pull request dialog, you can add information about the pull request in a comment. The text you add appears between the subject line and the log lines that Bitbucket and Git generate, and adds the text to the commit message for the merge.
- Select a merge strategy from the menu and then, select Merge.
Git merge strategies affect the way the Git history appears after a merge has occurred. Administrators can configure which merge strategies are available and which merge strategy will be the default. Learn more about pull request merge strategies
Auto-merge a pull request
In Bitbucket 8.15 and later, you can have your pull requests merged automatically by the system. For this, you need to select the same Merge button in the top-right corner of the pull request view. The clock icon on the button will let you know that auto-merge is available for a target repository.
The Merge button with the clock icon will be displayed when there's one or more merge checks that are still pending. If there are no merge checks or if all of them have already passed, the Merge button without the clock icon will be displayed.
The Merge button will be enabled as soon as the pull request is created unless there are merge conflicts.
When all merge checks have passed, Bitbucket will automatically merge the pull request on behalf of the user who submitted the pull request for auto-merge.
Enable auto-merge for pull requests
To enable auto-merge for pull requests in a project or repository:
Go to Project settings or Repository settings, respectively.
In the left menu, select Auto-merge.
Select Enable auto-merge.
If you’re enabling auto-merge for a repository in a project where auto-merge isn’t enabled, first select Use custom settings. Then, select Enable auto-merge.
Set a pull request to auto-merge
A pull request can be auto-merged when it has no merge conflicts and it isn’t ready to merge.
To auto-merge a pull request:
In the top-right corner of the pull request view, select Merge. The clock icon on the button will let you know that auto-merge is available for a target repository.
In the Merge pull request dialog, you have the same options that are available during manual merge, such as updating the commit message, deleting a source branch, or selecting a merge strategy.
Select Merge.
You can opt for auto-merge only if a pull request has some failed checks. If all checks of the pull request are successful, the usual manual merge operation will immediately take place.
When all merge checks have passed, Bitbucket will automatically merge the pull request on behalf of the user who submitted the pull request for auto-merge.
Cancel auto-merge for a pull request
You can cancel auto-merge if, for example, you decide to merge a pull request manually. To cancel auto-merge, select the Cancel merge button in the top-right corner of the pull request view.
What if a pull request can’t be auto-merged?
After you set your pull request to auto-merge, Bitbucket may not be able to auto-merge it and will cancel the operation. This can happen for one of the following reasons:
The pull request has merge conflicts.
The pull request has new code changes.
The target branch of the pull request was changed.
Merge checks on the pull request timed out.
The pull request couldn’t be merged for two weeks. (This is the default period but an administrator can set it to a different value.)
The pull request can't be merged with the selected merge strategy.
The user who set auto-merge is no longer active or doesn’t have permission to merge.
If Bitbucket cancels auto-merge due to any reason or another user cancels auto-merge manually, you’ll receive an email notification about this, similarly to other pull request activities. On the pull request overview page, the record about the cancelation and its reason will appear. For example, the record about the cancelation due to the pull request changing target branches.
Customize a commit message for your pull requests
A commit message appears in the Merge pull request dialog. In your project or repository, you can use the default template or create a custom template for commit messages. You can configure this behavior in the Commit message template section on the Merge strategies page. Under Template behavior, select one of the options:
Use the default template: you won’t be able to edit the commit message template in the merge strategies but you’ll be able to change your commit messages when merging pull requests.
Use a custom template: you’ll be able to edit the commit message template immediately, as well as change your commit messages when merging pull requests.
Learn more about pull request merge strategies
Delete source branch after merging
When merging a pull request, you can choose to Delete source branch after merging to keep your branch list clean.
If you choose to delete the source branch, any open pull requests targeting the source branch will be retargeted to the target branch. Select the affected pull requests link within the dialog to view the pull requests that will be modified.
Before deleting your source branch, Bitbucket will do some checks. The branch being merged will not be deleted if:
- The branch is the default repository branch.
- The user does not have permission to delete the branch.
Once accepted, the pull request is marked as merged on the Pull requests tab. If Bitbucket detects a conflict that prevents the merge, notifications are displayed on the Overview and Diff tabs of the pull request. Click More information to see instructions for how to resolve the conflict in your local repository.