DEV Community

Cover image for Complete guide about Mergify and the gain it represents.
Ankur Tyagi
Ankur Tyagi

Posted on • Originally published at theankurtyagi.com

Complete guide about Mergify and the gain it represents.

This tutorial will demonstrate how to use Mergify to create a Merge queue in your GitHub flow.

Understanding the fundamental building blocks of merge queues allows you to apply this knowledge in whatever way you see fit in the future.

Adding queues to your CI/CD pipeline with Mergify:

  • Mergify Save time by automating your pull requests and securing the code merge with a merge queue.
  • Mergify can assist you with a variety of tasks.
  • Mergify allows you to define your own rules.
  • When your pull request matches any of the rules you specified, their bot will take action. It can merge, close, comment, request a review, backport, copy, etc.
  • It will notify you of its progress and which rules may be triggered in real-time.

A Queue will keep your Merges safe.

Automate and protect your merges using the market's best and fastest merge queue.

Maintain the main evergreen branch and stop causing problems with your deployments.

TL;DR

  • What is Mergify
  • What problem does Mergify solve
  • Why Mergify
  • Why do we need Merge Queue
  • What is Merge Queue and what value does it provide
  • Why using a Merge Queue is the best option
  • Mergify Vs MergeQueue

Introduction

Merging code into branches could be a very time-consuming task, especially on big projects with many developers or in any case. So when you have a lot of branches and a lot of pull requests that have to be reviewed, approved, and merge in the correct order and it’s not just merging itself because for each pull request, you need to decide who the reviewers are.

You need to assign labels, perhaps rebase your branches, consider the most updated versions that have been pushed in the meantime to the main branch, and much more. Wouldn't it be nice if we could have a free automation tool that works with any CI and integrate natively with GitHub? It can do all the just mentioned.

Mergify revolutionized how we work with our pull requests and do our merges.

What is Mergify

Image description

Mergify is a tool that helps prioritize, queuing, and automatically merge your pull requests. It can also rebase and update your branches while commenting, labeling, assigning, and closing your pull requests.

If it sounds compelling, it’s because it is. But, of course, you can do some of these things in Github directly; well, yes, some features are covered by Github, but you either need to activate them manually or any way they are not as powerful as counterparts that Mergify provides and in other cases these features are simply missing from Github.

Mergify is a GitHub pull request automation tool with a merge tool.

Mergify gives user automation when you create a new project on GitHub. To design your merge policy, you write code. You won't have to wait for anything because it's automatic.
You will achieve a deployment rate of 10-20 times each day.

Mergify is a "Tools for GitHub" tool.

What problem does Mergify solve

Mergify is a powerful GitHub pull request automation engine that enables you to automate everything, particularly merging. You write the rules, and it takes care of the rest.

They also deal with more complicated use cases. For example, they offer a merge queue so that your pull requests are merged serially and tested by your CI one after the other, avoiding code regression.

Classic problem

A common issue is when a PR has been sitting for some time awaiting review. Because CI passed too long ago, you've merged many things into the main branch, and your PR is outdated. The CI stated that it is still green and that "it worked one week ago, so it is fine to be merged." So you approve it, merge it, and then problems arise due to the changes that were merged in between.

Another everyday use case is when you or a colleague is doing a PR and asks, "Hey, can you review it?" So you review it, approve it, and then realize the CI did not complete because your CI takes more than an hour. But, according to your rules, this is stupid because it is ready and has the appropriate label, approval, and CI passing.

Why Mergify

You can save time by having your pull requests automatically merge, comment, rebase, update, label, backport, close, and assign.

For example, suppose you want your pull request to be merged once your CI passes and the pull request has been approved. You write such a rule, and our engine merges the pull request as soon as it is ready.

Their goal is to make pull request management and automation simple. For example, you can use your bot to trigger a rebase of your pull requests or a backport to a different branch with a single comment.

Why do we need Merge Queue

Merging the separate work of a large team of experts into one codebase is a challenging task to carry out.

  • The problem lies deeper than our regular merging conflicts, which the version control is perfect at handling.

There are way more complex conflicts that experts can encounter when continuous changes are made to multiple fields of code built on one another.

Let me explain with an example to understand it in a better way

Using GitHub, you can gain a better understanding of the problem.

We create a Pull Request that passes the main branch's CI & there is another commit before our PR is merged. It makes no difference whether the commit is made by merging another PR or by committing directly to the main branch; the CI checks remain green even after the commit.

As novice maintainers, we would think that this is fine as long as the checks pass. As a result, we merge the PRs, and guess what? The production environment is at risk.

The requirement for Merge Queue arises because general CI checks or any version control system fail here.

You might be confused; even if all the checks pass, how can merging the PR break the code at production?

Let's say I'm adding a function call to some new code, and my colleague is editing it at the same time, perhaps modifying the signature or return values. Because the file I changed had no new modifications when my colleague committed, the CI would still pass.

Only merge queue can help solve this problem where Version control and even tests and checks in CI can’t help.

What is Merge Queue and what value does it provide

Every day large companies encounter millions of conflicts between daily changes that are solved by merging, where stakes are high, and 1 error can cost billions of dollars.

For example, At Netflix, developers merge and deploy over 300-600 pull requests every day.

More than a million customers depend on Netflix streaming services; an error while merging may fire up billions of dollars & customer dissatisfaction.

The tech expert team at Netflix reported a 4% chance of an actual conflict between two changes; this number grows to 30% with only 15 concurrent and potentially conflicting customization.

So these problems can occur almost every day for large companies.

Here comes the part of the Merge queue to solve that problem quickly.

A Merge Queue is exactly what its name implies: it is a queue to which you add your branch/Pull-Request in order for it to be merged.

Merge Queue is a First-In-First-Out queue that carries out the merge workflow for our Github repository.

It's always simple for developers to commit directly to the master branch. However, as the project grows in size and complexity, as well as the number of participants, branching becomes necessary.

Simply said, a merge queue is a mechanism that combines the benefits of directly committing to the master with the scalability of establishing branches.

Apart from the convenience of not having to wait for builds to merge, the main benefit of employing a Merge Queue is that it can help us avoid bad merges, saving us both time and money.

A merge queue solves this problem by updating any pull request that is out of sync with its base branch before merging it. The change makes the continuous integration system retest the pull request with the new code from the base branch, catching any potential regression.

Why using a Merge Queue is the best option

If you consider the ever-increasing size of your engineering team, its velocity at creating pull requests, and the emergence of bots that continuously generate code, the chance of breaking a production system arises as the system expands.

Over the last decade, the industry centered on building a pre-submit testing approach focused on individual changes and did not consider concurrent changes.

At Mergify, they envision that this has to change. However, the cost of faulty branches is too expensive, considering its consequences, such as delayed rollouts, deployment of rollbacks, and the hampering of developers' productivity due to local failure.

Mergify provides a merge queue for GitHub that is easy to set up and customize to your needs.

If you have been using Git for some time now, I am sure working with Pull Requests is now at your fingertips. You may have started getting irritated with merge conflicts a lot. But what if I tell you, even after merging the conflicts, we can't be sure if the pull request will break our production or not?

  • Have you ever thought about how enterprise projects are maintained?
  • How do so many contributors work together in sync without breaking the production?

Engineering teams at Shopify, Uber and almost every other company have faced the same issue with merging and used the same hammer to break and finish off the problem.

Many engineering teams and open-source projects introduce merge queues as part of their workflows.

Every day, Mergify merge code for top companies

  • Mozilla
  • Netflix
  • AXA
  • Uber
  • IBM
  • Airtable
  • Fedora and many more.

Image description

Mergify Vs MergeQueue

Mergify is a comprehensive automation service for pull requests, whereas MergeQueue is a simple merging queue.

Every large team requires a merge queue, but it is ineffective in the absence of automation.

Mergify is a MergeQueue alternative that is entirely automated.

Mergify provides the quickest merge queue in the industry at this moment.

Mergify allows you to define a variety of custom rules and workflows.

There are a variety of criteria for defining rules, such as the author of the pull request, the base branch, labels, files, and so on. With over 25k monthly active users, they are the industry expert and leader in code merge automation.

  • The quickest merge queues
  • Multiple and ordered queues
  • Complete automation

You can create your own conditions that can be used in pull request rules and queue rules to determine whether a pull request meets a specific rule.

If a pull request meets all of the conditions listed in a rule, the subsequent actions listed in that rule will be carried out. Conditions must be specified in the conditions section of the pull request rules or queue rules entries — see below for more information.

pull_request_rules:
  - name: automatic merge for main when reviewed and CI passes
    conditions:
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=main
      - label=ready-to-merge
    actions:
      merge:
        method: merge
Enter fullscreen mode Exit fullscreen mode

Visit the conditions doc page to learn more about the many sorts of conditions you can add.

Mergify executes the actions configured in that rule when a pull request matches the list of Conditions of a rule.

The actions should be placed in the pull request rules entry under the actions key — see below for an image of more information on how we added a comment.

pull_request_rules:
  - name: automatic merge for main when CI passes and 2 reviews
    conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
      - base=main
    actions:
      merge:
        method: merge
Enter fullscreen mode Exit fullscreen mode

You can add 15+ actions types to your PR:

  • assign
  • backport
  • close
  • copy
  • comment
  • delete_head_branch
  • dismiss_reviews
  • edit
  • label
  • merge
  • post_check
  • queue
  • rebase
  • request_reviews
  • review
  • update
  • squash

Image description

Learn more about actions.

Let's talk about an example "Use labels to merge important & urgent PRs."

Some pull requests may be more urgent when using the queue action than others. In that case, you could use a label to add a condition and set the priority of the queue action:

pull_request_rules:
  - name: automatic merge of 🚑 hotfix (high priority)
    conditions:
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=main
      - label=🚑 hotfix
    actions:
      queue:
        method: merge
        priority: high
  - name: automatic merge of bot 🤖 (low priority)
    conditions:
      - author~=^dependabot(|-preview)\[bot\]$
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=main
    actions:
      queue:
        method: merge
        priority: low
  - name: automatic merge for main when reviewed and CI passes
    conditions:
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=main
    actions:
      queue:
        method: merge
        priority: medium

Enter fullscreen mode Exit fullscreen mode

As the prior example demonstrates, the pull request will be submitted to the merge queue as soon as two contributors have approved it. Pull requests labeled "hotfix" will be merged first in the merge queue.

I strongly advise you to look at these excellent examples listed here.

Conclusion

The work of a developer does not finish with creating a pull request.

There are numerous variables to consider, such as:

  • Please do not fail the CI tests.
  • Reviewers, Who should I ask to look through my PR?
  • Conflicts, When it comes to rebasing, there are a lot of them!
  • Merging, I'm hoping it goes well.

And as we increase our teams, whether we're working at a startup or a large corporation, this becomes increasingly unpleasant.

So why not automate everything? Mergify does precisely that.

If you already have a GitHub account, sign up with Mergify & enable Mergify on your Git repository in a few steps and start automating.

That concludes this blog.

Today I hope you learned something new. Please like/share if you did so that it reaches others.

Follow Mergify on Twitter for the latest updates.

Twitter is a great place to follow my journey.

If you enjoyed this, sign up for my newsletter. It's completely free.

Top comments (0)