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

Bitbucket merge queues: Add to Merge Queue, setting one up, and the REST API

On a branch with a merge queue, a pull request is not merged directly: it goes into the queue, Bitbucket builds what the target branch would become with it, and merges it only when that build passes. Bitbucket Cloud has merge queues on its paid plans; Bitbucket Data Center has them from 10.2. From Atlassian's Manage pull requests with merge queues (Cloud), the Cloud REST reference and the Data Center 10.2 and 10.3 release notes.

Cloud: before you start

A paid plan (Standard or Premium), and Bitbucket Pipelines enabled for the repository.
Only a repository admin can create and manage merge queues.
Not on forks: a pull request from a fork cannot be merged into the parent repository through a queue.

Cloud: create and activate a queue

In the repository, select More actions (…) next to its name in the left sidebar, then Settings, Workflow, Merge queues, and Create a merge queue.
Give it a Name (it must match the key under merge-queues in bitbucket-pipelines.yml), the Target branch (the pull requests' destination branch), the Build concurrency (how many queue builds may run at once) and the Merge strategy (Merge commit, Squash or Rebase + merge), then Save. A new queue is INACTIVE.
In bitbucket-pipelines.yml on the target branch, add a merge-queues section beside pull-requests, with the queue's name as its key, for example merge-queues: / mergequeue-main: / - step:. Dynamic pipelines support it too.
From the … menu of the queue, select Activate. Pull requests to that branch then show Add to Merge Queue instead of Merge once their merge checks pass.

Without a matching merge-queues section, pull requests to that branch can become impossible to merge and stay open, with a message that the merge queue requirements are not met.

Cloud: what happens in the queue

After Add to Merge Queue, Bitbucket makes a merge result commit (what the target branch would become) and runs the queue's pipeline on it, on a temporary branch named bitbucket-merge-queue-*. Branch restrictions must not stop commits on that pattern.
When the build passes, Bitbucket updates the target branch and marks the pull request merged. Pull requests are validated and merged in the order they were added; with build concurrency above 1, several builds can run at once, but merges still follow that order.
When the build fails, or the pull request cannot be validated cleanly against the target branch and the pull requests ahead of it, it leaves the queue unmerged and stays Open. Builds of the pull requests behind it that included its changes are aborted and run again without them.
Queue builds get OIDC tokens with the target branch's settings, not the temporary branch's. A deployment limited to admins ("Only allow admins to deploy to this environment") can fail, because the pipeline after the merge can be started by the bitbucket-pipelines system user, who cannot be made an admin.
Pull requests can also be queued automatically when their builds pass, with the same checkbox as automatic merging when builds pass.

Cloud: managing a queue

On the Merge queues page, the … menu at the top right offers Drain (stop taking pull requests; those in the queue carry on), Clear (only when draining or inactive: remove every pull request, stop the builds, and leave the pull requests open), Deactivate (remove the queued pull requests; the branch merges normally again), Activate, and Delete (only when inactive or drained and empty). The same page lists the queued pull requests of each queue.

Cloud: the REST API

POST …/pullrequests/{id}/merge on a branch with an active queue adds the pull request to the queue. It answers 202 with the task-status address in Location, even when async is false, and calling it again returns the same address. Queues take merge_commit, squash and rebase_merge; without a strategy, the queue's own is used. A queue that is not taking pull requests gives 400; 503 means the queue could not be checked, so try again later.
GET …/merge/task-status/{task_id} says PENDING while the pull request is in the queue, with a queued_pullrequest once the queue has it: its status (QUEUED, PROCESSING, AWAITING_MERGE, MERGE_IN_PROGRESS, REMOVING) and rank, its place counted from 1. It says SUCCESS once merged, and returns an error (whose message can contain Markdown) if the pull request leaves the queue unmerged.
…/repositories/{workspace}/{repo_slug}/merge-queues lists the queues (target_branch filters them); …/merge-queues/{uuid}/queue lists the queued pull requests, and DELETE …/merge-queues/{uuid}/queue/{pullrequest_id} takes one out (202; the removal happens afterwards).
…/pullrequests/{id}/mergeability/checks includes a merge_queue_check when the branch needs queueing or the pull request is queued: required, blocking, queued and the queue's state (ACTIVE, PAUSED takes pull requests but does not merge them, DRAINING and SUSPENDED take none, INACTIVE needs no queueing).

Data Center

Merge queues came to Bitbucket Data Center in 10.2, the Long Term Support release of March 3, 2026. 10.3 (May 12, 2026) added webhook events for merge queues (for example when a merge result is being prepared or a queue branch is cleaned up), and a cascading merge whose next pull request targets a branch with a merge queue now adds that pull request to the queue instead of stopping for someone to queue it by hand.

Merge queues 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 with their merge checks, the merge queue among them. From version 1.0.49, on Bitbucket Cloud, its Merge on a branch with a merge queue adds the pull request to the queue, and the plugin says its place in the queue instead of waiting for the merge; refresh later to see it merged. From 1.0.50, its merge queue line says whether merging goes through the queue, whether the pull request is in it and the queue is paused, or that the queue is not taking pull requests now. 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: Bitbucket auto-merge · Bitbucket merge checks · Bitbucket merge strategies · pull request builds · Bitbucket pull request plugins for IntelliJ IDEA, compared · 日本語