β‘οΈ Getting Started π
Installation π
Mergify is a GitHub Application that operates on your GitHub repositories to automate them. You need to install Mergify on your GitHub Account to have it working.
Login to https://dashboard.mergify.io/
Click on
Enable Mergify on a new account
or go to https://github.com/apps/mergify/installations/newGitHub 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.

You will be redirected to the dashboard.
Configuration π
The Configuration File π
Mergify applies rules to your pull requests. To do that, you need to 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. The configuration file format is entirely documented in π Configuration File.
The Rules π
The configuration file is composed of a main key named pull_request_rules
which contains a list of rules.
Each rule is composed of 3 elements:
A name that describes what the rule does. Itβs not interpreted by Mergify and can be anything you like that helps you identify the rule.
A list of conditions. Each conditions must match for the rule to be applied.
A list of actions. Each action will be applied as soon as the pull request matches the conditions.
A First Rule π
Letβs create a first rule that will merge the pull request as soon as it has been approved by one contributor.
Hereβs the relevant configuration file content:
pull_request_rules:
- name: Automatic merge β¬οΈ on approval β
conditions:
- "#approved-reviews-by>=1"
actions:
merge:
method: merge
The
name
of the rule is not used directly by Mergify, but is really useful when Mergify will report its status and for debugging rules. We advise setting an explicity name that makes sense to you.The
conditions
defines the list of conditions that a pull request must match in order for the engine to execute the configured actions. In this example, there is only one condition to be met for the rule to be applied to a pull request. Theapproved-reviews-by
variable contains the list of collaborators that approved the pull request and. In this case, the variable must contains at least 1 member (note the length operator#
used here).The
action
is to merge of the pull request. It enabled by specifying themerge
action with amethod
parameter containing the merge method to use.
Note
Mergify is event-driven: rules are only executed when pull requests are updated or when the bot is manually triggered in a comment with @Mergifyio refresh (see βοΈ Commands).
Fore more details about the configuration file format, check π Configuration File.
Creating the Configuration File π
You can create your configuration file using your favorite text editor. However, writing and testing in the config editor can be easier. Go to your Mergify dashboard and pick the config editor for your organization. Then, select a repository where you enabled Mergify.

You can edit the default configuration provided as you wish. If your repository has existing pull requests, you can test your configuration against those by typing a pull request number in the form above.
When done, click on the Create a pull request with this configuration
button. A new pull request will be created on your repository with the new
Mergify configuration. You can merge them by clicking on the merge button.

Note
For security reason, Mergify will never automatically merge a pull request if it changes the Mergify configuration file.
Once your configuration is merged, Mergify will apply it to all your pull requests.
Understanding Mergify Check Report π
When a pull request is created in the repository, Mergify posts a status check about the state of the pull request according to the defined rules.

Note
When a pull request changes the configuration of Mergify, the status is
built with the current configuration (without the pull request change). The
Mergify configuration is validated and status is posted in the Summary
check.
When all the criterias of the rules are satisfied, Mergify executes the configured actions and e.g. merges the pull request.
Controlling Mergify with Commands π
Mergify also exposes a set of βοΈ Commands that you can trigger by commenting on the pull request.

You can consult the list of those commands on the βοΈ Commands page.