Mergify is a tool that helps manage pull requests more efficiently. Instead of looking at each event that happens within a pull request, Mergify checks the overall status to decide what to do next. This method is known as edge triggering.

Here’s how Mergify is set up:

Configuration File: You need to create a file in the root directory of your project. You can name it .mergify.yml, .mergify/config.yml, or .github/mergify.yml.
Rules: These are the conditions that need to be met for Mergify to take action.
Actions: These are the tasks Mergify performs once the rules are met.

Some Example Mergify Workflows#

pull_request_rules:
  - name: merge automatically when CI passes and PR is approved
    conditions:
      - "#approved-reviews-by >= 2"
      - "check-success=your-ci-name"
      - "base=main"
    actions:
      merge:

In this scenario:

The rule is called Automatic merge when CI passes and approved.
Mergify will check if the pull request has at least 2 approved reviews, if the specified CI checks have passed, and if the pull request targets the main branch.
If all these conditions are met, Mergify will automatically merge the pull request.

Example with a Queue#

You can also set up a merge queue. This means that instead of merging pull requests immediately when conditions are met, they are placed in a queue. They get merged one by one, in order.


pull_request_rules:
  - name: Automatic merge when CI passes and reviews approve
    conditions:
      - "#approved-reviews-by>=2"
      - check-success=CI # replace "CI" with the name of your CI status check
    actions:
      queue:
        merge_method: merge

In this setup:

When a pull request meets the specified conditions, it is added to the merge queue.
Once it reaches the front of the queue, Mergify merges it into the target branch and moves to the next one.

Some Example Mergify Workflows#

Example with a Queue#

Further Reading#