Skip to main content
All products
Repositories

Managing a merge queue

In this article

You can increase development velocity with a merge queue for pull requests in your repository.

Who can use this feature

People with admin permissions can manage merge queues for pull requests targeting selected branches of a repository.

Pull request merge queues are available in any public repository owned by an organization, or in private repositories owned by organizations using GitHub Enterprise Cloud. For more information, see "GitHub’s products."

Note: The pull request merge queue feature is currently in public beta and subject to change.

About merge queues

A merge queue can increase the rate at which pull requests are merged into a busy target branch while ensuring that all required branch protection checks pass.

Once a pull request has passed all of the required branch protection checks, a user with write access to the repository can add that pull request to a merge queue.

A merge queue may use GitHub Actions. For more information, see "GitHub Actions Documentation."

The merge queue creates temporary branches with a special prefix to validate pull request changes. The changes in the pull request are then grouped into a merge_group with the latest version of the base_branch as well as changes ahead of it in the queue. GitHub will merge all these changes into base_branch once the checks required by the branch protections of base_branch pass.

For information about merge methods, see "About pull request merges."

Notes:

  • A merge queue cannot be enabled with branch protection rules that use wildcard characters (*) in the branch name pattern.
  • A merge queue will wait for required checks to be reported before it can proceed with merging. You must update your CI configuration to trigger and report on merge group events when requiring a merge queue.

After grouping a pull request with the latest version of the target branch and changes ahead of it in the queue, if there are failed required status checks or conflicts with the base branch, GitHub will remove the pull request from the queue. The pull request timeline will display the reason why the pull request was removed from the queue.

Triggering merge group checks with GitHub Actions

You can use the merge_group event to trigger your GitHub Actions workflow when a pull request is added to a merge queue. Note that this is a different event from the pull_request and push events.

Note: If your repository uses GitHub Actions to perform required checks on pull requests in your repository, you need to update the workflows to include the merge_group event as an additional trigger. Otherwise, status checks will not be triggered when you add a pull request to a merge queue. The merge will fail as the required status check will not be reported.

A workflow that reports a check which is required by the target branch's protections would look like this:

on:
  pull_request:
  merge_group:

For more information, see "Events that trigger workflows."

Triggering merge group checks with other CI providers

With other CI providers, you may need to update your CI configuration to run when a branch that begins with the special prefix gh-readonly-queue/{base_branch} is created.

Managing a merge queue

Repository administrators can require a merge queue by enabling the branch protection setting "Require merge queue" in the protection rules for the base branch. For more information, see "Managing a branch protection rule."

Once you have enabled "require merge queue," you can also access the following settings:

  • Merge method: Select which method to use when merging queued pull requests: merge, rebase, or squash.

  • Build concurrency: Select the maximum number of pull requests to build (between 1 and 100). This setting limits the number of queued pull requests that can run CI checks at the same time.

  • Merge limits: Select the minimum and maximum number of pull requests to merge in a single group (between 1 and 100), and a timeout after which the queue should stop waiting for more entries and merge with fewer than the minimum number of pull requests.

  • Only merge non-failing pull requests: This setting determines how the merge queue forms groups of pull requests to be merged.

    If selected, only pull requests that are passing their required CI checks can be added to a group. This can be useful if you want to maintain a history where every commit is in a good state, or if you run different sets of checks for different pull requests.

    If unselected, pull requests that have failed required checks can be added to a group as long as the last pull request in the group has passed required checks. If the last pull request in the group has passed required checks, this means that the checks have passed for the combined set of changes in the merge group. Leaving this checkbox unselected can be useful if you have intermittent test failures, but don't want false negatives to hold up the queue.

  • Status check timeout: Choose how long the queue should wait for a response from CI before assuming that checks have failed.

Further reading