Configuration file

The file format for mergify.yml is fully described here. The main entry is a dict whose key is named rules. The value of the rules key must be a dict with the following optional keys:

Key name Value type Value description
default Rule The rules to be applied by Mergify by default. See Rule for the rule format. Or null to disable Mergify by default.
branches dict A dictionary where keys are string or regular expression (if starting by ^) to match against branch names and the values are of type Rule or null to disable Mergify on this branch.

Rule

A Rule is a dictionary with the following optional keys:

Key name Value type Value description
protection Protection The protection to be applied on pull requests.
disabling_label string A label name that will disable Mergify if it is applied to a pull request. Default is no-mergify.
enabling_label string A label name that will enable Mergify only if it is applied to a pull request. Default is null.
disabling_files array of string A list of files paths that disables Mergify if they are part of the pull request. Any file that changes the behavior of the continuous integration workflow should be listed. The default is [.mergify.yml]. Note that the engine always ignore pull requests that modify .mergify.yml anyway. Those pull requests will have to be merged manually, even if .mergify.yml is not listed in this setting.
merge_strategy Merge Strategy The method to use to merge pull requests.
automated_backport_labels dict A dictionary where keys are labels name and values are branch name. When a pull request is merged and labeled with one of the keys, a new pull request is created on the branch associated to the key. The new pull request have all commits cherry-picked from the original pull request.

Merge Strategy

A Merge Strategy defines the method to merge pull requests. It is a dictionary with the following optional keys:

Key name Value type Value description
method string Merge method to use. Possible values are merge, squash or rebase. Default is merge.
rebase_fallback string If method is set to rebase, but the pull request cannot be rebased, the method defined in rebase_fallback will be used instead. Possible values are merge, squash, none. Default is merge.

Protection

A Protection defines the safeguards that are needed to merge pull requests in a branch. It is a dictionary with the following optional keys:

Key name Value type Value description
required_status_checks Required Status Checks Require status checks to pass before merging. Set to null to disable.
required_pull_request_reviews Required Reviews The required criterias on code reviews for the pull request to be merged. Set to null to disable.
restrictions Restriction Restrict who can push to this branch. Team and user restrictions are only available for organization-owned repositories. Set to null to disable.
enforce_admins boolean Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to false to disable.

Required Status Checks

A Required Status Checks defines which other services must report a valid status check before a pull request can be merged. It is a dictionary with the following optional keys:

Key name Value type Value description
strict boolean Require branches to be up to date before merging. See Strict Merge.
contexts array The list of status checks to require in order to merge into this branch

Required Reviews

A Required Reviews defines what kind of reviews are needed for a pull request to be merged. It is a dictionary with the following optional keys:

Key name Value type Value description
dismiss_stale_reviews boolean Set to true if you want to automatically dismiss approving reviews when someone pushes a new commit.
require_code_owner_reviews boolean Blocks merging pull requests until code owners review them.
required_approving_review_count integer Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6. If you don’t need any reviewer, set required_pull_request_reviews to null instead.

Restriction

A Restriction defines a list of user or team for whom a restriction applies. It is a dictionary with the following optional keys:

Key name Value type Value description
users array The list of user logins with push access.
teams array The list of team slugs with push access

Default branch configuration

The default configuration for all branches is the following:

protection:
  required_status_checks: null
  required_pull_request_reviews:
    require_code_owner_reviews: false
    dismiss_stale_reviews: true
    required_approving_review_count: 1
  restrictions: null
  enforce_admins: false

enabling_label: null
disabling_label: no-mergify
disabling_files:
  - .mergify.yml
merge_strategy:
  method: merge
  rebase_fallback: merge
automated_backport_labels: null