Skip to main content

Managing a merge queue

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.

Note: The pull request merge queue feature is currently in limited 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."

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.

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.

About the merge group size setting

You can configure a merge queue's merge group size, which determines how many pull requests are included in each merge group. When there are no status check failures or merge conflicts, choosing the default "small" merge group size will form groups containing 2 pull requests. If you want to group more pull requests per group, you may choose the "medium" merge group size to form groups containing 5 pull requests each.

For information about how to enable the merge queue protection setting, see "Managing a branch protection rule."

Further reading