Skip to main content

Managing a merge queue

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

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

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 Enterprise Cloud 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."

Note:

  • A merge queue cannot be enabled with branch protection rules that use wildcard characters (*) in the branch name pattern.

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 Enterprise Cloud 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 by enabling the branch protection setting "Require merge queue" in the protection rules for the base branch.

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

Further reading