主なコンセプト

• Target branch - The branch you merge the pull requests into.
• Merge queue - A queue of pull requests that are validated in order before being merged to the target branch.
• Merge result commit - A temporary commit created by combining the pull request with the latest state of the target branch (and, depending on configuration, other pull requests ahead in the queue). This is the commit your CI validates.
• Checks / required builds - CI builds or other checks that must pass before a queued pull request is merged.

How merge queues work

At a high level:

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. Required builds and other checks run against this merge result commit.
5. If all checks pass, Bitbucket updates the target branch and marks the pull request as merged.
   If checks fail or conflicts are detected, the pull request is removed from the queue and does not merge.

Configure merge queues

You can configure merge queues at both project and repository level.

Project-level configuration

1. Go to Project settings, then Pull requests. 
2. Select Merge queue.
3. On the Merge queue page, use the Add merge queue setting to define merge queue behavior for one or more target branches in the project.
   Repositories in the project can inherit these settings.

Repository-level configuration

1. Go to Project settings, then Pull requests. 
2. Select Merge queue.
3. On the Merge queue page, use the Add merge queue setting to define or override merge queue behavior for specific target branches in this repository.

Settings you can configure

You can configure the following options:

• Select a target branch - Select branches to use for merge queue. 

  • Any branch - Apply this merge queue configuration to all branches in the project or repository.

  • Default branch - Apply the configuration only to the repository’s default branch.

  • Branch name - Apply to a single, specific branch name.

  • Branch pattern - Apply to branches matching a pattern (for example, release/*). This uses the same pattern semantics as branch permissions and required builds.

• Merge timeout - Defines how long a pull request can wait in the queue before it is automatically removed from the queue. Pull requests that exceed the timeout will not be merged by the queue.
  This is useful when builds are long-running or might get stuck. 
• Concurrent builds - Controls how many merge queue items can be processed and have builds running at the same time.
  For example, to process one pull request at a time, enter 1. 
  If you allow more pull requests to run validations in parallel, you will improve throughput at the cost of more concurrent CI load.

Restrict merge queues to project level

You can use project-level settings as the source of truth for merge queues and restrict or discourage per-repository overrides. This helps ensure consistent policies across all repositories in a project.

Configure required builds for pull requests and merge queues

Required builds work together with merge queues to ensure the merge result commit is validated before merging.

To configure the required builds, in the selected repository, go to Repository settings, then Pull requests and select Required builds. 

When you add or edit a required build, you can configure where the build must succeed before changes can be merged to the target branch using the Select execution types option.

Execution types settings

You can configure the following options:

• Pull request and merge queue - Requires a successful build on both:
  • The latest commit in the pull request, and
  • The merge queue’s merge result commit
    This is the default setting for existing required builds when merge queues are introduced.
• Pull request - Requires a successful build on the latest commit in the pull request before it can be merged to the target branch.
  Builds are not required for the merge result commit in the queue.
• Merge queue - Requires a successful build on the merge queue’s merge result commit before merging.
  This focuses validation on what will actually be merged. Repository admins can change the execution type for required builds at any time.

Using merge queues

This section explains what a merge queue looks like in Bitbucket Data Center and how to add or remove a pull request from the queue.

When you select Add to merge queue on a pull request, Bitbucket opens a confirmation dialog similar to the Merge dialog. It includes the configured merge strategy, an option to delete the source branch after the merge, and the merge message.

For repository admins, the dialog also shows an option to bypass the merge queue. System administrators can disable the bypass option globally by setting mergequeue.bypass=false in bitbucket.properties (if not configured, this setting deaults to true).

How long items remain in the queue

A PR remains in the merge queue until one of the following occurs:

• The pull request is merged.
• The pull request is manually removed from the queue.
• A required build - a merge queue check - fails or is rejected.

You can push new changes to the pull request while it is in the queue.

Add or remove a pull request from the queue

1. Open the pull request to a branch covered by a merge queue setting.
2. Select Add to merge queue to add the pull request to the queue.
3. Optional: To remove it from the queue, select Remove from merge queue on the pull request. 

View the merge queue for a repository

Each repository has a Merge queue page in the sidebar navigation. This page lists all pull requests currently in the queue for the selected target branch. The page defaults to the repository’s default branch, and includes a branch selector to view queues for other branches.

Batching strategy

Merge queues in Bitbucket Data Center process pull requests in queue order. A pull request is only merged if all earlier pull requests in the queue have successful checks and can be merged. If an earlier pull request fails its checks or its merge fails, the following pull requests in the queue are not merged in that run, and their validations may be rerun once the issue is resolved. This helps keep the target branch stable by ensuring each pull request is validated against the changes ahead of it in the queue.