Merging a pull request with a merge queue

In this article

If a merge queue is required by the branch protection setting for the branch, you can add your pull requests to a merge queue and GitHub will merge the pull requests for you once all required checks have passed.

Tool navigation

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 plans."

About merge queues

A merge queue helps increase velocity by automating pull request merges into a busy branch and ensuring the branch is never broken by incompatible changes.

The merge queue provides the same benefits as the Require branches to be up to date before merging branch protection, but does not require a pull request author to update their pull request branch and wait for status checks to finish before trying to merge.

Using a merge queue is particularly useful on branches that have a relatively high number of pull requests merging each day from many different users.

Once a pull request has passed all required branch protection checks, a user with write access to the repository can add the pull request to the queue. The merge queue will ensure the pull request's changes pass all required status checks when applied to the latest version of the target branch and any pull requests already in the queue.

A merge queue may use GitHub Actions or your own CI provider to run required checks on pull requests in a merge queue. For more information, see "GitHub Actions documentation."

For more information about merge queues, see "Managing a merge queue."

Adding a pull request to a merge queue

Note: You can use GitHub CLI to add a pull request to a merge queue. For more information, click the "GitHub CLI" tab at the top of this article.

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Pull requests.

    Screenshot of the main page of a repository. In the horizontal navigation bar, a tab, labeled "Pull requests," is outlined in dark orange.

  3. In the "Pull Requests" list, click the pull request you would like to add to a merge queue.

  4. Click Merge when ready to add the pull request to the merge queue. Alternatively, if you are an administrator, you can:

    • Directly merge the pull request by checking Merge without waiting for requirements to be met (bypass branch protections), if allowed by branch protection settings, and follow the standard flow.

    Screenshot of the merge queue options for a pull request.

    Note: You can click Merge when ready whenever you're ready to merge your proposed changes. GitHub will automatically add the pull request to the merge queue once required approval and status checks conditions are met.

  5. Confirm you want to add the pull request to the merge queue by clicking Confirm merge when ready.

With GitHub CLI, you can use the gh pr merge command to add a pull request to a merge queue. If you are targeting a branch that requires a merge queue, this command automatically adds the pull request to the queue if required checks have passed. If required checks have not passed, this command enables auto-merge for the pull request. For more information, see gh pr merge in the GitHub CLI manual.

Removing a pull request from a merge queue

To remove a pull request from a merge queue, you must navigate to the repository's page on GitHub.com. You cannot use GitHub CLI to remove a pull request from a merge queue.

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Pull requests.

    Screenshot of the main page of a repository. In the horizontal navigation bar, a tab, labeled "Pull requests," is outlined in dark orange.

  3. In the "Pull Requests" list, click the pull request you would like to remove from a merge queue.

  4. To remove the pull request from the queue, click Remove from queue.

    Screenshot of the merge queue message at the bottom of a pull request. The "Remove from queue" button is outlined in dark orange.

Alternatively, you can navigate to the merge queue page for the base branch, click ... next to the pull request you want to remove, and select Remove from queue. For information on how to get to the merge queue page for the base branch, see the section below.

Viewing merge queues

You can view the merge queue for a base branch in various places on GitHub. You cannot use GitHub CLI to view a merge queue.

You can view the merge queue for a base branch in various places on GitHub.

  • On the Branches page for the repository. We recommend you use this route if you don't have or don't know about a pull request already in a queue, and if you want to see what's in that queue. For more information, see "Viewing branches in your repository."

    Screenshot of the "Branches" page for a repository. A link, labeled "33 pull requests queued to merge," is outlined in dark orange.

  • On the pull request page when merge queue is required for merging, scroll to the bottom of the timeline and click the merge queue link.

    Screenshot of the merge queue message at the bottom of a pull request. The "merge queue" link is outlined in dark orange.

  • The merge queue view shows the pull requests that are currently in the queue, with your pull requests clearly marked.

    Screenshot of the merge queue.

Understanding why your pull request was removed from the 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, the pull request will be removed from the queue. The pull request timeline will display the reason why the pull request was removed from the queue.

There are a number of reasons a pull request can be removed from a merge queue:

  • Configured CI service is reporting test failures for a merge group
  • Timed out awaiting a successful CI result based off the configured timeout setting
  • User requesting a removal via the API or merge queue interface
  • Branch protection failure that could not automatically be resolved