View as Markdown

Rule Syntax

How to write a Mergify workflow rule, from the structure of pull_request_rules to its conditions and actions.

Workflow Automation rules live under the pull_request_rules key in your configuration file, where each rule pairs a set of conditions with the actions Mergify runs when a pull request matches them. For a gentle introduction, see the Workflow Automation overview. This page is the field-by-field reference.

Fields

Section titled Fields

pull_request_rules is a list, and each entry is a single rule: a YAML dictionary where name, conditions, and actions are required, while description and disabled are optional.

actions#

Actions

The actions to perform when the rule matches.

conditions#

List of conditions

The conditions that must be met for the rule to be evaluated.

description#string or null·defaultnull

A description of the rule.

disabled#

DisabledDict

or null·defaultnull

If the rule is disabled, the reason why it's disabled.

name#string

The name of the rule. This is used when reporting information about a rule. It's not possible to have two rules with the same name.

Conditions

Section titled Conditions

conditions is a list of expressions describing which pull requests the rule applies to. A pull request must satisfy every condition in the list for the rule to match:

conditions:
  - base = main
  - label = ready-to-merge

Each condition is built from an attribute (such as base, label, or #approved-reviews-by), an operator (such as =, >=, or ~=), and usually a value. See the attributes list and operators list for the full set.

To express “any of” or “none of” instead of “all of”, group conditions with the and, or, and not operators. The same condition syntax also powers Merge Queue and Merge Protections, so what you learn here carries over.

Actions

Section titled Actions

actions is a dictionary that maps an action name to its parameters. A single rule can run several actions, and Mergify runs them all when the conditions match:

pull_request_rules:
  - name: warn and label pull requests in conflict
    conditions:
      - conflict
    actions:
      comment:
        message: "@{{author}} this pull request is now in conflict 😩"
      label:
        toggle:
          - conflict

The {{author}} placeholder is a template that Mergify fills in with the pull request’s data. Browse every available action and its parameters in the Actions catalog.

Combining Rules

Section titled Combining Rules

Rules are evaluated independently: Mergify checks each one against the pull request, and every rule whose conditions match runs its actions. Order the rules however reads best, since matching does not stop at the first hit. For when an action re-runs versus stays put, see how rules are evaluated.

Disabling a Rule

Section titled Disabling a Rule

Set disabled with a reason to keep a rule in the file but stop it from running. The reason is shown in the configuration check so others know why:

pull_request_rules:
  - name: automatic merge
    disabled:
      reason: paused during the release freeze
    conditions:
      - "#approved-reviews-by >= 1"
    actions:
      merge: # merge with default options

Validating Your Rules

Section titled Validating Your Rules

Mergify validates your configuration on every push and reports problems in the “Checks” tab of your pull request. To catch mistakes earlier, validate and simulate rules locally with the Mergify CLI:

Terminal window
mergify config validate
mergify config simulate https://github.com/owner/repo/pull/142

See Validation and Troubleshooting for the full workflow.

Was this page helpful?

Edit this page on GitHub