Merge a pull request

When the desired number of reviewers have approved a pull request, you can merge the pull request if you have write (or admin) permission on the repository. If you've been touching the same code as someone else, you may have a merge conflict that you need to resolve locally. After you merge a pull request, you can revert the pull request to remove the merge commit from the repository.

Merge a pull request

Merging your changes is the final stage of the pull request process. To merge a pull request:

  1. Click the Merge button.

  2. (Optional) Update the Commit message with more details.

  3. (For Git repositories only) Select a Merge strategy from these options:

    • Merge commit—Keeps all commits from your source branch and makes them part of the destination branch.
      This option is the same as entering git merge --no-ff in the command line.

    • Squash—Combines your commits when you merge the source branch into the destination branch.
      This option is the same as entering git merge --squash in the command line.

      Note: When you enter git merge --squash in the command line locally, the pull request will remain in the ‘open’ state after you push the changes to Bitbucket. This is because we use the commit graph to detect that changes were applied, and when ‘squash merge’ is used, we cannot detect that the pull request was merged or display an accurate diff. The pull request will now contain identical changes between the two branches, so the pull request will show no diff. However, you will be able to see the commit history of the pull request and view the individual commits.

    • Fast forward—Moves commits from the source branch to the destination branch (if the destination has no new commits).
      This option is the same as entering git merge --ff-only in the command line.

    For more details on these two types of merge strategies, refer to Merge strategies below.

  4. (Optional) If you're merging two branches in the same repository, you can select the Close source branch checkbox to remove the branch from the list of repository branches.

  5. Click the Merge button.

Bitbucket will also mark any other pull requests that are composed only of commits from the branch you are merging as ‘merged’. For example, if another open pull request is a branch off the one you are merging, but has no additional commits, the other open pull request will also be marked as ‘merged’.

Merge checklist

To set up a merge checklist

You must be a repository administrator to add a merge checklist to a repository. For more details, see Suggest or require checks before a merge.

As you're about to merge your pull request, you may see a Merge checklist. This checklist is a list of items that your administrator requests that you resolve before you merge your code. Any checklist items with a warning label are unresolved.

If your organization has a Premium plan, then the workspace admin can require that merge checks are resolved before the pull request can be merged.

If this checklist item has a warning label

Then your pull request

At least {#} approvals

doesn't have that number of approvals

At least {#} successful builds on last commit

doesn't have that number of successful builds for the most recent commit

No failed builds on last commit

has failed builds on the most recent commit

Resolved pull request tasks

has open pull request tasks

Viewing your merge checks

As an administrator or a reviewer on a pull request, you can view the merge checks (required or otherwise) in the top merge check panel on the right sidebar to see what has and has not yet been completed prior to approving the pull request.

Merge strategies

The merge strategy defines how you want the commit history to appear when you merge a pull request. Both strategies merge all your commits from your source branch to the destination branch. The type of strategy you choose to use depends on the workflow you've created for your workspace and how you use your repository.

When to do a merge commit

Select Merge commit when you want to maintain an exact history of changes. Merge commits are also useful if, as part of your workflow, pull requests are large in scope and you review commits individually. Because this strategy keeps all commits during the merge, you'll still see all commits from the source branch on the Commits page.

When to do a squash merge

Select Squash to make your commits list less cluttered, which results in less time to search for commits that introduce a bug (with a git bisect) and provides an easy-to-follow commit history. Because this strategy combines all commits when you merge, you'll only see one commit on the destination branch on the Commits page.

When to do a fast-forward merge

Select Fast forward if the destination branch has no new commits since you created the source branch. Fast-forward merges move the source branch tip up to the destination branch tip, combining commit histories. Because this strategy moves the source branch's commits to the destination branch, you'll still see all commits on the Commits page.

Revert a merged pull request

While you can't undo a pull request, you can revert the merged commit from a pull request if necessary. Bitbucket takes two steps to revert a pull request: 1) Bitbucket creates a new branch with one commit that reverses the merged commit. 2) Bitbucket creates a new pull request for the branch and commit.

To revert a pull request:

  1. From the pull request, click the Revert button in the top right.

  2. (Optional) From the Revert pull request dialog, change the Branch name for the new branch you're about to create.

  3. Click the Revert button. Once you click Revert, Bitbucket creates the new branch. Even if you cancel the pull request, the revert branch remains in the repository.

  4. The Create a pull request page opens with the revert branch as the source. After you add your reviewers and make additional changes, click Create.

Additional Help