Manage pull requests with merge queues

Merge queues help keep important branches stable by testing what will actually be merged before it lands. Instead of merging pull requests directly into a target branch, Bitbucket adds them to a queue, prepares a merge result for each pull request, and only updates the target branch when the configured merge queue builds pass.

Use merge queues when you want to:

• Reduce post-merge breakages and semantic conflicts between pull requests.

• Keep important branches “green”.

• Make merge behavior more predictable in high-traffic repositories.

はじめる前に

Pre-requisites

• You must be on a paid (Standard or Premium) plan.

• Bitbucket Pipelines must be enabled for the repository.

• A configured merge queue and a matching merge-queues pipeline definition in bitbucket-pipelines.yml .

How merge queues work

Bitbucket validates queued pull requests in the order in which they were added to the queue, and if a pull request fails, any queued work that depends on that pull request’s build being successful is re-evaluated.

1. A pull request is created targeting a branch with a configured merge queue.

2. When ready, the pull request is added to the merge queue.

3. Bitbucket creates a merge result commit that represents what will land in the target branch.

4. The configured merge queue build is run against this merge result commit.

5. If the configured merge queue build passes, Bitbucket updates the target branch and marks the pull request as merged.
   If the build fails or any conflicts are detected, the pull request is removed from the queue and does not merge.

Successful CI

When multiple pull requests are queued and their merge-queue builds pass:

• pull requests are merged in order into the target branch.

• If build concurrency allows, Bitbucket may run validations for multiple queued pull requests at the same time; merges still follow queue order.

Failing CI

If a queued pull request fails the configured merge queue build (or can’t be validated cleanly against the latest target + queued changes):

• That pull request is removed from the queue and remains Open.

• Any merge-queue builds for pull requests behind it that included the failed pull request’s changes are aborted, and those pull requests are re-built without the failed pull request’s changes (because their “dependency” is no longer in the queue).

Configuring Pipelines to run on a merge queue

Merge queues introduce a new Pipelines selector: merge-queues. When a pull request is added to a merge queue, Bitbucket triggers the pipeline defined under that selector.

Add a merge-queues section under pipelines: in your target branch’s bitbucket-pipelines.yml:

重要な注意事項

• The key under merge-queues: (for example, mergequeue-main) must exactly match the merge queue name you configured in the UI.

• If there is no matching merge-queues configuration, pull requests targeting that branch can become non-mergeable and remain Open with messaging indicating the merge queue requirements aren’t satisfied.

• merge-queues is also supported with dynamic pipelines (same concept as pull-requests). See: for more details.

Create a merge queue

1. リポジトリに移動します。

2. Select Repository Settings in the left sidebar, then select Workflow, and then select Merge queues.

3. Select Create a merge queue.

4. Add the following to the corresponding fields:

   • Name - must match your bitbucket-pipelines.yml key under merge-queues

   • Target branch - this must be the pull request destination branch, not the source branch

   • Build concurrency - the maximum number of merge queue builds that can run parallelly for the pull requests in the merge queue

   • Merge strategy supported: Merge commit, Squash, Rebase + merge

5. [保存] を選択します。

6. When the merge queue is created, it is in an INACTIVE state.

7. In order to activate the newly created merge queue, you must first configure the merge-queue pipeline and then select the … (more options) dropdown and select Activate to enable the merge queue.

How you know it’s enabled: pull requests targeting that branch will show “Add to Merge Queue” instead of “Merge” once merge checks pass.

Add a pull request to a merge queue

1. Open a pull request targeting a branch with a configured merge queue.

2. Once merge checks pass, select Add to Merge Queue.

3. Bitbucket queues the pull request and runs the configured merge-queue pipeline.

4. If merge queue’s build passes, the pull request is merged automatically. If the merge queue’s build fails, the pull request is removed from the queue and remains Open.

To see the list of queued pull requests, select Repository settings on the left sidebar, then select Workflow, and then select Merge queues. Once you see the list of merge queues, you can select a particular merge queue to see more details.

Automatic queuing when builds pass

Similar to Automatic merging when builds pass, you can configure pull requests to be automatically queued once builds/checks pass using the same checkbox flow referenced here:

Manage a merge queue (admin only)

To manage a merge queue, select Repository settings on the left sidebar, then select Workflow, and then select Merge queues. On the Merge queues page, select the … button in the upper-right corner.

Within that dropdown menu, you can choose to do any of the following:

• Drain: Stop accepting new pull requests into the queue; pull requests already in the queue continue processing. This places the merge queue in the Draining state.

• Clear: Available only when the queue is in a Draining or an Inactive state. Removes all pull requests from the queue and stops in-progress merge queue builds. Pull requests return to Open and must be queued again.

• Delete: Available only when the queue is Inactive or Drained and empty. Deletes the merge queue configuration.

• Activate: Activates the merge queue, new pull requests will be accepted into the queue.

• Deactivate: Deactivates the merge queue. All existing pull requests inside the queue will be removed and the merge queue will be put into an Inactive state. In the inactive state, the merge queue is configured but not active on the target branch, so pull requests are merged normally.

既知の制限事項

• If merge queues are used with deployment restrictions like “Only allow admins to deploy to this environment”, a deployment may fail because the post-merge pipeline can be initiated by the bitbucket-pipelines system user (not a real user that can be granted admin permissions).

• Merge queues are not supported on forked repositories. If your repository is a fork, you cannot use the merge queue feature to merge a pull request into the parent repository.

その他の情報

• Bitbucket creates temporary branches matching the pattern bitbucket-merge-queue-* to run merge queue builds. Make sure there are no branch restrictions that block this pattern (for example, permissions that prevent commits from being created on branches matching bitbucket-merge-queue-*).

• For merge queue builds, Bitbucket generates OIDC/JWT tokens by inheriting the compliance and security settings from the target branch that the merge queue is configured on, not from the temporary bitbucket-merge-queue-* branch where the build actually runs.