Bitbucket Cloud and Data Center · Merging pull requests · October 28, 2026

Bitbucket merge strategies: merge commit, squash, fast-forward and rebase

When you merge a pull request in Bitbucket you pick a merge strategy, and it decides how the history of the target branch looks afterwards. Cloud and Data Center have nearly the same list; the differences are one strategy, where the settings live, and the API names. From Atlassian's Merge a pull request (Cloud) and Pull request merge strategies (Data Center).

The strategies

• Merge commit (--no-ff): Cloud merge_commit · Data Center no-ff
• Fast-forward (merge commit if needed) (--ff): not in Cloud · Data Center ff
• Fast-forward only (--ff-only): Cloud fast_forward · Data Center ff-only
• Rebase, merge (rebase + merge --no-ff): Cloud rebase_merge · Data Center rebase-no-ff
• Rebase, fast-forward (rebase + merge --ff-only): Cloud rebase_fast_forward · Data Center rebase-ff-only
• Squash (--squash): Cloud squash · Data Center squash
• Squash, fast-forward only (--squash --ff-only): Cloud squash_fast_forward · Data Center squash-ff-only

• Merge commit keeps every commit of the source branch and adds a merge commit, even when the source is already up to date. It is Data Center's default.
• Fast-forward only and Squash, fast-forward only refuse the merge when the source branch is behind the target. Data Center's plain Fast-forward makes a merge commit instead in that case.
• The two rebase strategies put a new copy of each source commit on top of the target; Atlassian notes that the pull request's branch itself is not changed.
• Squash makes one new commit on the target with all the changes.

Where the default and the allowed ones are set

• Cloud: Repository settings > Merge strategies, where a repository admin picks the Default merge strategy, the one preselected in the Merge pull request dialog. A project admin can set one in Project settings > Workflow > Merge strategies; a repository added to the project has to be set to inherit the project's settings to follow it (Set up a merge strategy for a project).
• Data Center: Project settings or Repository settings > Merge strategies, with a toggle per strategy and Set as default. Repositories inherit the project's settings unless set to Use custom settings. From Bitbucket 8.10 a project admin can choose Don't allow changes to merge strategies; custom repository settings are then deleted and the project's apply.
• In Data Center, only the strategies enabled there can be chosen when merging. In Cloud, the API gives each pull request the strategies available for its target branch.

The commit message

• Cloud: in the Merge pull request dialog you can update the Commit message with more details before you merge; Atlassian limits it to 128 KiB (Merge a pull request). The API's merge request takes it as message.
• Data Center: a commit message template, set with the merge strategies of the project or the repository, fills the title (required) and the body of the message in the merge dialog, with variables such as the pull request's title and ID, the branch names and the approvers. The message stays editable. A separate setting decides how many commit summaries go into it when merging or squashing; zero leaves them out (Pull request merge strategies).
• Which strategies use it: the message goes on the commit the merge makes, the merge commit or the one squash commit. Fast-forward only makes no commit (the target branch just moves to the source's last commit), and Rebase, fast-forward puts copies of the source commits on top, each with its own message, so neither has a commit to put it on. Data Center's Fast-forward uses it only when it has to make a merge commit.

The usual surprises

• Squashed locally, the pull request stays open. After git merge --squash on your machine and a push, Bitbucket Cloud cannot tell from the commit graph that the pull request was merged; it stays open with no diff. Merge with Squash in Bitbucket instead.
• Fast-forward only refuses. The target got new commits since the branch was made. Rebase or merge the target into your branch and push, or pick a strategy that makes a merge commit.
• Rebase pitfalls (Data Center): building on a branch that was merged by rebase can apply duplicate, empty commits, and a git pull of a branch Bitbucket rebased can merge the old commits with their rebased copies. A rebase that clashes with changes made at the same moment ends in a transactional failure: wait, reload and merge again.
• Conflicts: with any strategy, Bitbucket leaves the repository as it was. Resolve the conflict locally and push, then merge again.
• Through the API: Cloud's merge endpoint takes merge_strategy, and the API reference lists merge_commit as its default, so send the one you want; a pull request's destination.branch carries merge_strategies and default_merge_strategy. Data Center takes strategyId; the enabled ones are in the repository's settings/pull-requests, under mergeConfig.
• A token that cannot merge (Data Center): merging creates a commit, so project and repository access tokens cannot merge, and a personal token needed Repository admin in a public report (details under API token on the product page).

Merge strategies in IntelliJ IDEA

Pull Request Inbox for Bitbucket, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pull requests of Bitbucket Cloud and Bitbucket Data Center in an IDE tool window. Its Merge dialog offers only the strategies the target branch allows, with the repository's default preselected, and takes your own commit message and closing the source branch. From version 1.0.52 the message field takes several lines, as on the web page, so a squash commit can have a body under its first line; for Fast-forward only and Rebase, fast-forward the field is off and says why. It also says in words which merge checks are still open. The review inbox and the merge checks are free; approving, commenting and merging are Pro, with a 30-day trial.

Get it on JetBrains Marketplace

Bitbucket is a trademark of Atlassian Pty Ltd; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian or JetBrains.

More: merge conflicts · Bitbucket auto-merge · Bitbucket merge checks · modify a pull request based on out-of-date information (Data Center) · Bitbucket default reviewers · Bitbucket pull request plugins for IntelliJ IDEA, compared · 日本語