How Merge Queues Made My Life Easier

How did we automate our development process with Mergify and Merge queue?

If your team is working on a software project with GitHub, chances, you struggled when multiple developers try to merge pull requests to the main branch at the same time. If it sounds familiar to you, this article might be helpful for you.

TLDR — I created a GitHub repo with built-in PR automation and merge queue configuration. Have a look!

How did our development process work?

We were two teams that consisted of 10 developers that worked on the same mono-repo. Our development process was pretty much like that: each developer assigned to a ticket creates a new feature branch and adds some commits in the process of development. In the end, the developer makes a feature branch PR. This PR requires some CI process to run (tests, lint, etc). Additionally, each PR has to be approved by another developer. When a PR is approved, and CI checks pass, this PR can be merged into the main branch.

Check the diagram of the development process below.

Old Development Process

What was the problem?

When we started to deliver faster and created more PRs, we created a protection rule for our main branch. This rule ensures PRs will be up to date before they are merged with the main branch.

The reasons for adding this rule were:

1. To ensure that new code is being tested along the current code in the main, to avoid breaking the tests on merge, requiring that each PR will be up to date with the main branch. This ensures that the code being merged is as current as possible and minimizes the risk of conflicts or other issues arising when the code is merged.
2. To simplify the review process, when PRs are up to date, reviewers can more easily understand the changes being proposed and provide more accurate feedback. This can help to streamline the review process and make it more efficient.

Overall, adding a protection rule to your GitHub branch that requires each PR to be up to date can help to improve the quality and reliability of your code, as well as encourage better collaboration and communication within your team.

GitHub Settings for Branch Protection Rule

However, this rule may cause a new problem for the developers because some of them may find it frustrating to have to constantly update their PRs in order to keep them up to date. This could lead to a decrease in morale and potentially even hinder collaboration.

Update Branch View :(

What was the solution?

To solve that issue one of our developers, Ophir Yael, figured out that to avoid the “Update Branch” issue, we can use a merge queue and specifically Mergify. Mergify is a tool that automates the process of merging pull requests (PRs) on GitHub.

What is Merge Queue?

A merge queue is a feature used by some version control systems and GitHub to manage the process of merging branches. When a merge request is made, the changes from one branch are added to a queue, and the system waits until the changes can be safely merged into the main development branch.

The purpose of a merge queue is to ensure that the main branch won’t break. In our case, only one merge is performed at a time, which can help to reduce the risk of merge conflicts and skews. It can also help to ensure that the merged code is correct and meets the necessary quality standards. How did we integrate Merge Queue into our CI pipeline?

The suggested solution was when a PR is submitted on GitHub, it is added to the merge queue managed by Mergify. GitHub will then automatically check the PR for any merge conflicts or other issues that need to be resolved before the PR can be merged. If there are no issues, once it's turned Mergify will automatically merge the PR into the main development branch. If there are issues that need to be resolved, Mergify will notify the PR author or other relevant parties, and the PR will not be merged until the issues are resolved.

New Development Process

How to start?

Before we start, I should say that Mergify has different plans, and not all features are available in the free plan, but I created a really cool example with the free plan. This application use jest and configures GitHub actions to simulate a CI process like a real application.

1. Login to Mergify dashboard.
2. Click on Enable Mergify on a new account or go to https://github.com/apps/mergify/installations/new
3. GitHub will now offer you to select the repositories you want to give Mergify access to. Select any repository you like, or all if you wish.
4. You will be redirected to the dashboard.

Now let's create a simple NodeJS application.

1. Clone your repository to a local folder.
2. run npm init -y to initialize your application
3. run npm install -D jest
4. create__tests__ folder
5. add __tests__/simple.test.js

describe("Filter function", () => {
    test("it should filter by a search term (link)", () => {
      expect(1+1).toBe(2);
    });
  });

6. Add a test script in the scripts section in package.json should be like that

{
  "name": "merge-queue-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "jest": "^29.3.1"
  }
}

7. Let’s try to run the test npm test the result should show you that the test passed.

8. Let's continue and create our GitHub workflow to create the CI process, create .github/workflows/node.js.yml .

# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v3
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm test

I will not deep dive into workflow configuration, this is for a different blog post, but in general, this workflow runs the previous test on different Nodejs versions (14,16,18). When a PR is opened against the main branch.

9. Add .mergify.yml in the root directory.

pull_request_rules:
  - name: merge using the merge queue
    conditions:
      - base=main
      - "#approved-reviews-by>=1"
      - check-success=build (14.x)
      - check-success=build (16.x)
      - check-success=build (18.x)
    actions:
      queue:
        method: squash
        name: default

The pull_request_rules property is a list of rules that specify the conditions under which a specific action should be taken on a pull request. Each rule consists of a set of conditions and an action to take if the conditions are met. In general, this rule adds 5 different conditions base=main means that this rule will be affected only by PR that will be merged into the main branch. #approved-reviews-by>=1 means that each PR requires at least one approval before it will be merged. The next three conditions check-success=build mean that merge will wait until the CI process is successful in our case we configured a workflow that runs tests on three different NodeJS versions (14, 16,18).

10. The actions sections means which actions Mergify will do after the above conditions are matched, In this case, we changed the merge method to squash and set the name of the queue (default). see screenshots below to see how it looks on Github and Mergify dashboard

Mergify Dashboard Queue Section

GitHub Checks Section

The full example can be found in this GitHub repo.

Conclusion

Using Mergify and a merge queue can be a useful approach for automating the management of pull requests in a GitHub repository.

Mergify is a tool that listens for events in a repository’s pull request timeline and takes actions based on configured rules. It can be used to automate various tasks, such as labeling, commenting, or merging pull requests.

The merge queue is a list of pull requests waiting to be merged. It can be used to manage the order in which pull requests are merged and to ensure that certain pull requests are prioritized over others.

Together, Mergify and the merge queue can help streamline the code review process and reduce the workload on maintainers. They can ensure that changes are promptly reviewed and merged when they are ready while still allowing maintainers to have control over the process.

Overall, using Mergify and a merge queue can be a useful way to automate the management of pull requests and improve the efficiency of the code review process.

Thanks to Ophir Yael for helping with this article.

Level Up Coding

Thanks for being a part of our community! Before you go:

• 👏 Clap for the story and follow the author 👉
• 📰 View more content in the Level Up Coding publication
• 🔔 Follow us: Twitter | LinkedIn | Newsletter

🚀👉 Join the Level Up talent collective and find an amazing job