---
title: Rule Syntax
description: 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](/configuration/file-format), 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](/workflow). This
page is the field-by-field reference.

## 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.

| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `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 | `null` | A description of the rule. |
| `disabled` | DisabledDict or null | `null` | 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

`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:

```yaml
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](/configuration/conditions#attributes-list) and
[operators list](/configuration/conditions#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](/configuration/conditions#combining-conditions-using-logical-operators).
The same condition syntax also powers [Merge Queue](/merge-queue) and
[Merge Protections](/merge-protections), so what you learn here carries over.

## 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:

```yaml
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 uses [variable
substitution](/configuration/data-types#variable-substitution): Mergify fills it
in with the pull request's data. Browse every available action and its
parameters in the [Actions catalog](/workflow/actions).

## Combining Rules

Mergify checks every rule against the pull request, and matching does not stop at
the first hit: each rule whose conditions match runs its actions.

Rule order still decides one thing. `close`, `delete_head_branch`, `merge`,
`queue`, `rebase`, `squash` and `update` refuse to run twice in the same
evaluation. When two matching rules both carry one of them, the rule listed
first in the file runs it, and the later rule's check reports that another
action of that kind already ran. Put the rule you want to win above the others.

For when an action re-runs versus stays put, see
[how rules are evaluated](/workflow#how-rules-are-evaluated).

## 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:

```yaml
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

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](/cli/config):

```bash
mergify config validate
mergify config simulate https://github.com/owner/repo/pull/142
```

See [Validation and Troubleshooting](/configuration/file-format#validation-and-troubleshooting)
for the full workflow.