close
The Wayback Machine - https://web.archive.org/web/20220321113921/https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/using-a-merge-queue
Skip to main content
Free, Pro, & Team
English
Sign up
 
Repositories
Free, Pro, & Team
English
Sign up

 

Using a merge queue

In this article

You can increase development velocity by enabling merge queues for pull requests in your repository.

People with admin permissions can configure 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. Organizations owners can request early access to the beta by joining the waitlist.

About pull request merge queue

Merge queues for pull requests can increase the rate at which pull requests are merged into a busy default branch, whilst ensuring that CI checks pass.

Merge queues use GitHub Actions. For more information about actions, see "GitHub Actions."

Once a pull request has passed any required checks and approvals, a contributor with write access can add the pull request to the merge queue. The queue then creates a temporary branch with that pull request and any pull requests ahead of it in the queue, and triggers any required continuous integration (CI) checks.

The merge queue creates temporary preparatory branches to validate pull requests against the latest version of the base branch. To ensure that GitHub validates these preparatory branches, you may need to update your CI configuration to trigger builds on branch names starting with gh-readonly-queue/{base_branch}.

For example, with GitHub Actions, adding the following trigger to a workflow will cause the workflow to run when any push is made to a merge queue preparatory branch that targets main.

on:
  push:
    branches:
    - main
    - gh-readonly-queue/main/**

Once CI checks pass, GitHub merges the pull request by fast-forwarding the default branch. The merge queue will use merge commits if the "Require linear history" branch protection setting is turned off, and the "Rebase and merge" method otherwise.

For information about merge methods, see "About pull request merges." For information about the "Require linear history" branch protection setting, see "About protected branches."

Note: During the beta, there are some limitations when using the merge queue:

  • The merge queue cannot be enabled on branch protection rules using wildcards (*) in the name.
  • There is no support for squash merge commits. (Only merge commits and "rebase and merge" commits are supported.)

If there are failed 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 has been removed from the queue.

Managing pull request merge queue

Repository administrators can configure merge queues for pull requests targeting selected branches of a repository. The requirement to use a merge queue is a branch protection setting called "Require merge queue" that can be enabled in branch protection rules.

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

Further reading