Bitbucket Cloud pull request merge strategies: when to merge, squash, or fast-forward

Problem and takeaway

Your team opens pull requests into `main`, but the commit history is either cluttered with merge bubbles or too collapsed to audit. The useful takeaway is to match the merge strategy to the branch lifecycle instead of using one setting for every repository: use merge commits on release branches where audit traceability matters, squash feature branches into `main` or `develop` for a clean summary, and use fast-forward only for short-lived branches that are already directly ahead of the target.

This guide covers Bitbucket Cloud. Bitbucket Server and Data Center may expose different settings. The repository settings paths described here reflect the current Cloud console, but Atlassian can change the UI without notice, so verify the exact menu labels in your instance.

Decision and constraints

Decision: which merge strategy to offer or enforce per branch pattern. Constraints:

• Preserve authorship and the original commit sequence where auditors need it.
• Avoid rewriting history on branches other teams have already consumed.
• Satisfy required approvals, branch permissions, and resolve-all-tasks rules, which are enforced separately from merge strategy.
• Keep `main` readable enough for release notes and incident investigation.

Supported options compared

Strategy	What happens on merge	Traceability	Target history	Best for	Avoid when
Merge commit	Keeps every source commit and adds a merge commit on the target branch.	High; preserves integration evidence and original authors.	More history; merge bubbles can clutter `main`.	Release branches, hotfix branches, shared integration branches.	Frequent small feature merges where a linear summary is preferred.
Squash	Collapses the source branch commits into one new commit on the target. Source commits remain on the source branch.	Medium; the squash commit is recorded, but per-commit context is lost.	Clean; one commit per feature.	Feature branches merged into `main` or `develop`.	Branches other teams have based work on; branches needing per-commit blame.
Fast-forward	Moves the target pointer forward to the source commit with no merge commit.	Low; no explicit merge metadata.	Linear; cleanest graph.	Short-lived trusted branches already up to date with the target.	Branches that have diverged or need proof that integration testing occurred on a merged branch.

Trade-offs

Merge commit

A merge commit preserves the exact sequence of integration, which helps auditors and incident reviewers see when a feature entered `main`. The downside is history noise: every approved pull request adds a merge bubble, and reverting a feature requires reverting the merge commit correctly rather than a single squashed commit.

Squash

Squashing produces a clean target history and simpler release notes because each feature appears as one commit. The trade-off is lost context: the original commit messages and authorship are preserved on the source branch, but `git blame` on the target points to the squash commit, not the original author. Do not squash branches that other teams have already merged or branched from, because the new commit hash on `main` will not match their history.

Fast-forward

Fast-forward is the cleanest graph, but Bitbucket Cloud only offers it when the source branch is directly ahead of the target. If the branches have diverged, you must rebase or update the source branch first. A fast-forward also hides that integration testing happened on a potentially stale branch, because there is no merge commit to inspect.

Configure merge strategies in Bitbucket Cloud

Required permissions: repository administrator or project administrator. Changes affect future pull requests; existing open pull requests may keep their previously selected strategy until the pull request is refreshed or reloaded.

1. Open the repository in Bitbucket Cloud.
2. Go to Repository settings > Branch management.
3. Find the branch pattern or branch permissions section for the target branch, such as `main` or `release/*`.
4. Select the allowed merge strategies for that pattern. For example, allow merge commit on `release/*` and squash on feature branches merged into `main`.
5. Set required minimum approvals and any resolve-all-tasks rules in the same branch permission screen. These are enforced independently of the merge strategy.
6. Save the changes.

Risk: changing the strategy does not retroactively alter merged pull requests, but it changes what merge options appear for new pull requests. Communicate the change to the team before updating shared branch patterns.

Validate with a scratch branch

Run Git commands in a local terminal where you have cloned the repository and have write access. Push results to Bitbucket Cloud.

1. Create a scratch branch from `main`:

   git checkout main
   git pull origin main
   git checkout -b pr-merge-test-
   

2. Add two unique commits:

   echo "test commit one" > test-merge.txt
   git add test-merge.txt
   git commit -m "Add test commit one"
   
   echo "test commit two" > test-merge.txt
   git add test-merge.txt
   git commit -m "Add test commit two"
   
   git push origin pr-merge-test-
   

3. Open a pull request from `pr-merge-test-` to `main` in Bitbucket Cloud.
4. In the pull request merge dropdown, select each strategy in turn on a separate test target or cancel before completing, then inspect the resulting commit graph and commit messages. Do not merge all three strategies into the same `main` branch without reverting between tests.
5. Expected checks:
   • Merge commit: `git log --graph --oneline main` shows both source commits plus a merge commit.
   • Squash: `main` shows one new squash commit; the source branch still contains the two original commits.
   • Fast-forward: `main` pointer moves to the second source commit with no merge commit, available only if `main` has not advanced since the branch was created.
6. Review the pull request activity and audit log in Bitbucket Cloud to confirm the merge author and chosen strategy were recorded.

Placeholders: replace `` with a short identifier such as a ticket number or initials, and replace `main` with your actual default branch name if different.

Limitations and practical verification

• Merge strategy selection does not override branch permissions, required approvals, or resolve-all-tasks rules.
• Squashing creates a new commit hash on the target, so it can break consumers who based work on the pre-squash branch.
• Fast-forward is unavailable unless the source is directly ahead of the target.
• UI paths and available strategies may vary by Bitbucket Cloud plan or workspace configuration.

Practical check: after any configuration change, open a new pull request against the affected branch pattern and confirm the merge dropdown shows the expected strategies. After a test merge, run `git log --graph --oneline` locally or inspect the commit graph in Bitbucket Cloud to verify the strategy behaved as intended.

Rollback

If you change the branch management settings and the wrong merge options appear, return to Repository settings > Branch management and restore the previous strategy selection. If an incorrect merge reaches `main`, revert it locally and push the revert: for a merge commit, use `git revert -m 1 `; for a squash or fast-forward, revert the resulting commit normally. Test reverts on a scratch branch before applying to `main`.