merge-queue

Subscribe to all “merge-queue” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

→ ~ cd github-changelog
→ ~/github-changelog|main git log main
showing all changes successfully

Pull request merge queue (public beta)

Today we are announcing the public beta of pull request merge queue for repos on GitHub Enterprise Cloud and open source organizations! 🎉

Merge queue helps increase velocity in software delivery by automating pull request merges into your busiest branches.

Pull request merge queue

Before merge queue, developers were often required to update their pull request branches prior to merging to ensure their changes wouldn't break the main branch when merged. Each update resulted in a fresh round of continuous integration (CI) checks that would have to finish before the developer could attempt to merge. If another pull request got merged, every developer would have to go through the process again.

Merge queue automates this process by ensuring each pull request queued for merging is built with the pull requests ahead of it in the queue.

Queueing a pull request to merge

If your pull request targets a branch that uses merge queue, instead of merging your pull request directly when it meets the requirements to merge, you will add it to the queue by clicking Merge when ready from the pull request page or from GitHub Mobile.

Queue to merge

The queue then creates a temporary branch that contains the latest changes from the base branch, the changes from other pull requests already in the queue, and the changes from your pull request. CI then starts, with the expectation that all required status checks must pass before the branch (and the pull requests it represents) are merged.

If a queued pull request has merge conflicts or fails any required status check, it is automatically removed from the queue when it reaches the front, and a notification is sent. Once the problem is resolved, it can be added back to the queue.

Learn more about merging a pull request with merge queue from the pull request page. You can also queue your pull request on the go using the beta version of GitHub Mobile from iOS TestFlight or Google Play (Beta)!

Viewing the queue

Always know where you are in the queue.

The queue details page, which can be accessed from the Branches page or pull request page, shows the pull requests in the queue and status for each, including the required status checks and estimated time to merge. It also shows how many pull requests have been merged and the trend over the last 30 days.

Merge queue details page

Depending on your permissions, you can also remove a pull request from the queue or clear the queue from this page.

Getting started

Merge queue can help improve overall velocity and avoid manual branch updates that impact developer productivity. Learn more about how to enable merge queue on your busiest branches.

We want to hear from you on how we can improve merge queue! Join the conversation in the merge queue public beta discussion.

See more

Merge group webhook event and GitHub Actions workflow trigger

This feature is available to repositories enrolled in the Pull Request Merge Queue beta.

A new webhook event and GitHub Actions workflow trigger (merge_group) makes it easier to run required status checks on merge groups created by merge queue. A merge group includes the changes from one or more pull requests and must pass the status checks required by the target branch.

A merge_group webhook event, which currently has one supported action (checks_requested), is sent after a merge group is created and informs receivers, including GitHub Actions, when status checks are needed on the merge group. The event payload includes head_sha, the commit SHA that should be validated and have status reported on using check runs or commit statuses. For GitHub Actions, status is reported automatically at the conclusion of jobs in the triggered workflow.

To trigger a GitHub Actions workflow for a merge group, the merge_group trigger should be used. The following example triggers on individual pull requests and merge groups targeting the main branch:

# Trigger this workflow on individual pull requests and merge groups that target the `main` branch
on:
  pull_request:
    branches: [ main ]
  merge_group:
    branches: [ main ]

A push event is still sent when a merge group branch is created, and will trigger a GitHub Actions workflow. However, unlike a merge_group event, a push event does not include the target branch of the merge group.

Learn more about using merge queue.

Learn more about the new GitHub Actions merge_group workflow trigger and the merge_group webhook event.

See more

Pull Request Merge Queue Limited Beta

Pull Request Merge Queue is now available in limited beta. Learn more about the feature and how to request early access.

Why a merge queue?

Maintaining high velocity and keeping your main branch green can be a challenge today. Many repositories try to do this by requiring all pull requests be up to date with the main branch before merging. This ensures the main branch is never updated to a commit that has not passed all required status checks, but forces developers to update (or rebase) their pull request branches multiple times and then wait for status checks to complete before trying to merge again. On some projects, status checks can take 30 or more minutes and if another pull request gets merged during this time, the process starts over (for everyone). This can have a significant impact on the overall velocity of the team and make it harder for developers to move onto their next task.

Merge Queue provides the benefits of requiring pull request branches to be up to date before merging, but without requiring developers to go through this process.

How it works

Merge Queue works by validating different combinations of pull requests identified as “ready to merge” in parallel so that pull requests can merge efficiently and without the typical delays that exist between merges today.

GIF of merge queue demo

Once a pull request has been approved and has passed all required status checks, a user with write access in the repository can queue the pull request to be merged. The pull request branch does not need to be up to date with the base branch before being queued. The merge queue then creates a temporary branch that includes the pull request and any non-failing pull requests ahead of it in the queue. This branch is based on the latest version of the base branch and is what the history of the base branch will look like if it passes all required status checks. Assuming it does pass these checks, the base branch is fast-forwarded and the pull request is marked as merged.

Early access

Merge Queue is currently available in limited beta. This gives us the opportunity to better understand your requirements as we improve the quality and capability of the feature. In the first phase of this beta, access to the feature is limited to a select number of organizations that meet certain requirements like having a consistently high volume of changes from multiple users being merged each day.

Organization admins can request early access for their organization by joining the waitlist: https://github.com/features/merge-queue/signup. You will need to provide the name of a repository in this organization that you plan on using merge queue on, but you will have the opportunity to test the feature on other repositories during the beta. We will contact you prior to onboarding to work through the details.

Early access will expand to more organizations over the coming months.

Learn more

For the latest updates on this feature, see the public roadmap issue and #merge-queue posts in the GitHub Changelog.

To learn more about configuring and using the feature once it is available to you, start with “Adding a pull request to the merge queue“.

See more