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

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 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