Configuration File Format

The configuration file for Mergify should be named .mergify.yml and must be placed in the root directory of your GitHub repository. Mergify uses the default repository branch configured on GitHub to read the configuration file — usually master. The file format is YAML.

The file main entry is a dictionary whose key is named pull_request_rules. The value of the pull_request_rules key must be a list of dictionary.

Each dictionary must have the following keys:

Key Name

Value Type

Value Description



The name of the rule. This is not used by the engine directly, but is used when reporting information about a rule.


array of Conditions

A list of Conditions string that must match against the pull request for the rule to be applied.


dictionary of Actions

A dictionary made of Actions that will be executed on the matching pull requests.

The rules are evaluated in the order they are defined and, therefore, the actions are executed in that same order.


Here’s a simple example of a configuration file:

  - name: automatic merge when CI passes and 2 reviews
      - "#approved-reviews-by>=2"
      - status-success=Travis CI - Pull Request
      - base=master
        method: merge

See Example Rules for more examples.


Usually .mergify.yml configuration change should be done via a pull request, in order for Mergify to validate it.

However if you are creating the initial configuration or want to validate it locally before sending a pull request, you can use:

$ cd <my_project>
$ curl -F 'data=@.mergify.yml'

Or by uploading the configuration file with this form: