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 is now generally available!

Today we are announcing the general availability of pull request merge queue! 🎉

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

Before merge queue, developers would often need to update their pull request branches prior to merging to ensure their changes wouldn't break the main branch because of incompatibilities with pull requests already merged. Each of these updates caused a new round of continuous integration (CI) checks that would have to finish before the developer could attempt to merge. Merge queue automates this process by ensuring each pull request queued for merging is tested with any other pull requests queued ahead of it.

Merge queue is available on private and public repos on the GitHub Enterprise Cloud plan and all public repos owned by organizations.

Check out this video demo of how merge queue works.

Updates

Over the last few months, we've been busy fixing bugs and responding to feedback. As part of the general availability, we're announcing the following updates:

  • New: A merge_group webhook event with an action of destroyed is now published when a merge group is destroyed for any reason, including when it's merged or invalidated because a pull request is removed from the queue.
  • Fixed: The before and created properties of the push webhook event published when a temporary branch is created by the queue are now set to reflect a branch was created
  • Changed: Jumping to the front of the queue is now only available to admins by default in repos on GitHub Enterprise, but can be granted to individual users and teams using a custom repository role. Previously, any user with write access could jump the queue, but admins did not have a way to limit access to it or grant it to users without write access.
  • Fixed: A pull_request.dequeued webhook event is now consistently published whenever a pull request is removed from the queue for any reason, including when it has been merged by the queue.

Learn more

For more on how to get started with merge queue, check out details on our blog!

A special thanks

A huge shout out and thank you to our customers in the community that participated in the public beta of this feature. Your input will help teams prevent traffic jams on their busiest branches! Hooray! ✨

See more

Pull request merge queue (public beta): API support and recent fixes

As we work towards general availability of pull request merge queue, we want to thank everyone that has provided feedback ❤ (keep it coming!) and let you know about some recent fixes and new API support.

See the public beta announcement to learn more about merge queue and how it can help increase velocity by automating pull request merges into your busiest branches.

🆕 API support

You can now interact with merge queue programmatically using new GraphQL APIs. Add or remove a pull request from the queue, see which pull requests are queued, get details about a queued pull request, and more. For example:

Call the enqueuePullRequest mutation to add a pull request to the queue or dequeuePullRequest to remove a pull request.

Use the mergeQueue field on Repository to list its contents or configuration. Use the mergeQueueEntry field on PullRequest to get details about a queued pull request including its state, position in the queue, estimated time to merge, and more.

🐛 Fixes

Some of the more noteworthy fixes made since the public beta launch:

  • Fixed: GitHub Actions workflows would not trigger on merge_group events in some repos
  • Fixed: failing queued pull request would remain failing even after checks were rerun and and passed
  • Fixed: confusing “pushed a commit that referenced this pull request” message would appear in the timeline
  • Fixed: commits could be pushed to queue-created prep branches (note: these commits were ignored and not merged, but it created confusion for some users)

Get started

Interested in merge queue? Learn how to get started.

Questions or suggestions? Join the conversation in the merge queue public beta discussion.

See more

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