TABLE OF CONTENTS

• Introduction
• Mergify
• Features
• Automatic merges
• Merge Queue
• Installing
• Configuration
• Example
• Conclusion

Introduction

Merging code into a branch can be a really time-consuming task, especially on large projects with many developers, or if you have a large number of Pull Requests that have to be reviewed, approved, and merged in the correct order. Also, if before your PR gets merged, other PRs get merged to main then your PR gets outdated. Then GitHub's CI tests will take place and if they get passed then we'll have to click on merge to get the PR merged. This can also be automated using Mergify. Pretty cool right!! So, in this blog, we'll be learning what Mergify is and how we can get started with it and use it to make our lives easier as a developer.

If you are more into visual learning, Do check out this video from Kunal Kushwaha:-
Video

Mergify

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. In simple terms, Mergify is a GitHub pull request automation tool with a merge tool. But there's a lot more to it that it can do. The best part is you don't need to learn any other technology, it gets integrated into GitHub.

Features

Automatic merges

You can customize automatic merge behavior and once that criteria/conditions such as CI tests pass, your PRs will be merged automatically. This can be done by describing your pull request conditions in a YAML file. You can match any pull request based on any criteria.

Merge Queue

As I explained about outdated PRs in the introduction. You should not merge outdated PRs and it can be time-consuming to keep the PRs up to date. This is where the merge queue comes into the picture. Your pull requests are merged serially and tested by your CI one after the other, avoiding code regression.

• When multiple pull requests are mergeable, they are scheduled to be merged sequentially, and are updated on top of each other. The pull request branch update is only done when the pull request is ready to be merged by the engine, for example when all conditions are validated.
• That means that when a first pull request has been merged, and the second one is outdated like you can see in this image, Mergify will make sure that pull request 2 is updated with the latest tip of the base branch before merging.

Installing

• First, we need to login into Mergify and allow access to our Github repository. This should install Mergify in our Github account.

• Click on Enable Mergify and then select all repositories or any specific repository as per your requirement.

• Now, you'll be seeing a dashboard. Here you can manage your selected repositories, write configuration files (write rules and then actions associated with them), merge queues, and many more.

• Now, in order to connect your repository with Mergify in order to apply all the rules and actions you define, create a Mergify configuration in each repository where Mergify is used.

The configuration file should be created in the root directory of the repository and named either .mergify.yml or .mergify/config.yml or .github/mergify.yml. As the file name implies, the configuration file format is based on YAML, a simplistic file format for data.

Configuration

Configuration file documentation

You can get started by using the code in Config Editor in Mergify.

pull_request_rules:
  - name: Automatic merge on approval
    conditions:
      - "#approved-reviews-by>=1"
    actions:
      merge:
        method: merge

It consists of:-

• Name of your rule explaining what the rule does.
• Conditions to be checked and verified for the action to take place.
• Actions that will take place upon verification of the conditions.

Example

Let's see an example. We'll try the merge configuration written above which automatically merges the pull request if one or more reviewers approve the pull request.

• Here, you can see a pull request that has been raised.

• I'll just approve the pull request.

• Voila! the Mergify bot automatically merges the pull request.

You can also auto-assign reviewers based on the type of file changed. Example: If python files and modified in the PR then assign them to person A, if java files are changed, assign it to person B, and so on.

pull_request_rules:
  - name: assign PRs with Python files modified to Rishwanth
    conditions:
      - "check-success=ci/circleci: validate"
      - files~=\.python$
    actions:
      assign:
          add_users:
              - rishwanthram

This is just a small example among the endless amazing things that Mergify can do. Here is a list of actions that you can perform using Mergify.

Conclusion

In this blog, you have learned how to get started with Mergify. Mergify is a great tool that can help in the automation when working with version control systems and save a lot of time. I hope you learned something from this blog and will try Mergify. You can go to Mergify to read the official documentation and learn more about it.

PS: I've posted this blog on HashNode as well. If you like it, do upvote it in HashNode that'll be helpful. Link

Thanks For Reading!