Github Pull Request Merge Queue

Recently GitHub announced Pull Request Merge Queue.

In this blog, I will talk about what is a merge queue and how it can be useful for your team.

What was the challenge before merge queue?
Before merge queue, developers had to update their pull requests before merging to ensure their changes wouldn’t conflict with their already merged changes. This requires extra time and extra efforts of your CI checks and reviews, which could slow down your development process.

Solution:
1. Reliability: merge PRs in the correct order
2. Developer experience: reduce the time spent waiting for CI checks and reviews
3. Performance: maximize the number of PRs merged per day with minimum latency

What is a merge queue?
Github’s merge queue is a feature designed to streamline the process of merging pull requests. It allows you to merge pull requests in a specific order, and it will automatically merge the next pull request in the queue once the previous pull request is merged.
specially in busy repositories where multiple developers are contributing concurrently. It is a great way to ensure that the code is merged in the correct order and that the code is not broken by other developers’ changes.

Here is a video from GitHub explaining merge queue in detail.

Github also builds a merge queue dashboard with the state of the queue and some interesting stats about remaining time. This is a great feature to clearly understand the state of the queue and how long it will take to merge your pull request.

Here’s how it works:
1. When a pull request is added to merge queue, a temporary branch is created. This branch has all the latest changes from the default base branch, pull request which are already in the queue and changes from your current pull request.
2. Once the CI starts running, all the changes from the temporary branch are applied to the pull request. This ensures that the pull request is tested with the latest changes from the default branch and other pull requests in the queue.
3. If a merge fails, the pull request is removed from the queue and the developer is notified. This ensures that the default branch is not broken by a pull request that is not ready to be merged.
4. If a merge succeeds, the pull request is merged into the default branch and the next pull request in the queue is merged.

How to use it:
1. Go to your repository’s settings page.
2. Click on settings/branches.
3. Under Branch protection rules, click on Add rule.
4. In the Branch name pattern field, enter the name of the branch you want to protect. This is usually the default branch of your repository.
5. Under Protect matching branches, select Require merge queue.
6. Configure other settings as per your requirements, like Merge method, Build concurrency, Merge limit, etc.
7. Click on Create to create the branch protection rule.

Now, If you’re using Github Actions as your CI, you will need to create a workflow file to enable merge queue.
In your workflow, it has to update to trigger on the `merge-group` event, when a pull request is added to the merge queue.

name: CI CD
on:
 pull_request:
 // add your merge group here
 merge_group:
jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v3
 - name: Run tests
 run: |
 echo "Running tests"

What if you have more than 5 separated workflows in your repository?
You would need to add merge group to all of them.
The merge_group trigger is necessary for the merge queue to know when to execute the associated workflow. It’s how they communicates with your Continuous Integration (CI) system or any other third party service that you might be using for your CI.

Check out the github official documentation for more details on [merge queue].

Thank you for reading this blog. I hope you found it useful.