---
title: Mergify Conditions
description: Everything you need to know when writing conditions in Mergify
---

A condition is a boolean expression evaluated against a pull request's attributes to determine whether a rule applies.

## Structure of a Condition

The grammar for a condition is:

`[ "-" ] [ "#" ] <attribute> [ <operator> <value> ]`

### Modifiers

- The optional minus (`-`) prefix negates the condition ("not").
- The optional hash (`#`) prefix evaluates the length of a list attribute.

### Attributes

Attributes represent properties of a pull request: number of approvals, labels,
status of CI checks, and so on.

### Operators

When the attribute is a list, comparison operators behave as if "any" is used on
the list: the condition is true if any element matches.

```yaml
# True if any check named `test` succeeds.
- check-success = test
# True if any modified file starts with foo/
- files ~= ^foo/
```

### Values

Values can be strings, numbers, or Booleans, depending on the attribute.

For example:

`#approved-reviews-by >= 2`

- Attribute: `approved-reviews-by` (list of approved reviewers).
- Operator: `>=`.
- Value: `2`.
- The `#` prefix evaluates the length of the list.

Boolean attributes are used on their own or negated with `-`:

```yaml
# True if the PR is merged
- merged
# True if the PR is open
- -closed
```

## Attributes List

| Attribute name | Value type | Description |
| --- | --- | --- |
| `added-files` | list of string | The files that are added by the pull request. |
| `added-lines` | list of string | The lines that are added by the pull request. Only usable as `#added-lines` for the number of added lines. |
| `approved-reviews-by` | list of string | The list of GitHub user or team login that approved the pull request. Team logins are prefixed with the `@` character and must belong to the repository organization. This only matches reviewers with `admin`, `write` or `maintain` permission on the repository. |
| `assignee` | list of string | The list of GitHub user or team login that are assigned to the pull request. Team logins are prefixed with the `@` character and must belong to the repository organization. |
| `author` | string | The GitHub user or team login of the author of the pull request. |
| `base` | string | The name of the branch the pull request should be pulled into. |
| `body` | string | The content of the pull request description without Markdown/HTML comments. |
| `body-raw` | string | The content of the pull request description. |
| `branch-protection-review-decision` | `APPROVED` or `CHANGES_REQUESTED` or `REVIEW_REQUIRED` or null | The review decision. This indicates if `CODEOWNERS` have reviewed the pull request when the `Require Review from Code Owners` branch protection rule is enabled. |
| `changes-requested-reviews-by` | list of string | The list of GitHub user or team login that have requested changes in a review for the pull request. |
| `check` | list of string | The list of checks for that pull request. |
| `check-failure` | list of string | The list of checks that failed for the pull request. Checks that report being cancelled, timed out, and action required are also considered as failures. |
| `check-neutral` | list of string | The list of checks that are neutral for the pull request.  |
| `check-pending` | list of string | The list of checks that are pending for the pull request. |
| `check-skipped` | list of string | The list of checks that was skipped for the pull request. |
| `check-stale` | list of string | The list of checks that are stale for the pull request. |
| `check-success` | list of string | The list of checks that successfully passed for the pull request. |
| `check-timed-out` | list of string | The list of checks that timed out for the pull request. |
| `closed` | boolean | Whether the pull request is closed. |
| `closed-at` | date-time or null | The time the pull request was closed at. |
| `co-authors` | list of CommitAuthor | The list of co-authors on the pull request (excluding merge commits and bots). |
| `commented-reviews-by` | list of string | The list of GitHub user that have commented in a review for the pull request. This only matches reviewers with `admin`, `write` or `maintain` permission on the repository. |
| `commits` | list of Commit | The list of commits of the pull request. The index 0 is the first commit, while -1 is the last commit. |
| `commits-behind` | list of string | The list of commits between the head of the base branch and the base of the pull request. This can only be used with the length operator as `#commits-behind`. |
| `commits-unverified` | list of string | The list of commit messages that are marked as unverified by GitHub. |
| `conflict` | boolean | Whether the pull request is conflicting with its base branch. |
| `created-at` | date-time | The time the pull request was created at. |
| `current-datetime` | date-time | The current date and time. |
| `deleted-lines` | list of string | The lines that are deleted by the pull request. Only usable as `#deleted-lines` for the number of deleted lines. |
| `dependabot-dependency-name` | list of string | The dependency-name value included in the Dependabot commit message. |
| `dependabot-dependency-type` | list of string | The dependency-type value included in the Dependabot commit message. |
| `dependabot-update-type` | list of string | The update-type value included in the Dependabot commit message. |
| `depends-on` | list of string | The list of dependencies to other pull request in the format `owner/repo#prnumber`. |
| `deployment-failure` | list of string | The list of deployments that failed for the pull request. |
| `deployment-success` | list of string | The list of deployments that successfully passed for the pull request. |
| `dismissed-reviews-by` | list of string | The list of GitHub user login that have their review dismissed in the pull request. |
| `draft` | boolean | Whether the pull request is in draft state. |
| `files` | list of string | The files that are modified, deleted or added by the pull request. |
| `head` | string | The name of the branch where the pull request changes are implemented. |
| `head-repo-full-name` | string | The head branch repository full name (complete version with the organization name). |
| `label` | list of string | The list of labels of the pull request. |
| `linear-history` | boolean | Whether the pull request commits history is linear (no merge commit). |
| `locked` | boolean | Whether the pull request is locked. |
| `merge-commit-sha` | string or null | The merge commit SHA of the pull request returned by GitHub. |
| `merged` | boolean | Whether the pull request is merged. |
| `merged-at` | date-time or null | The time the pull request was merged at. |
| `merged-by` | string or null | The GitHub user that merged the pull request. |
| `mergify-configuration-changed` | boolean | Whether the pull request contains changes in the configuration file. |
| `milestone` | string or null | The milestone title associated to the pull request. |
| `modified-files` | list of string | The files that are modified by the pull request. |
| `modified-lines` | list of string | The lines that are modified by the pull request. Only usable as `#modified-lines` for the number of modified lines. |
| `number` | integer | The pull request number. |
| `queue-dequeue-reason` | `NONE` or `PR_MERGED` or `PR_MERGED_INTERMEDIATE_RESULTS_SKIPPED` or `PR_DEQUEUED` or `PR_DEQUEUED_FROM_PARTITION` or `PR_AHEAD_DEQUEUED` or `BATCH_AHEAD_FAILED` or `PR_WITH_HIGHER_PRIORITY_QUEUED` or `SCHEDULED_FREEZE_STATUS_CHANGED` or `SPECULATIVE_CHECK_NUMBER_REDUCED` or `CHECKS_TIMEOUT` or `CHECKS_FAILED` or `QUEUE_RULE_MISSING` or `BASE_BRANCH_MISSING` or `BASE_BRANCH_CHANGED` or `PR_UNEXPECTEDLY_FAILED_TO_MERGE` or `BATCH_MAX_FAILURE_RESOLUTION_ATTEMPTS` or `PR_CHECKS_STOPPED_BECAUSE_MERGE_QUEUE_PAUSE` or `CONFLICT_WITH_BASE_BRANCH` or `CONFLICT_WITH_PULL_AHEAD` or `BRANCH_UPDATE_FAILED` or `DRAFT_PULL_REQUEST_CHANGED` or `PULL_REQUEST_UPDATED` or `MERGE_QUEUE_RESET` or `INCOMPATIBILITY_WITH_BRANCH_PROTECTIONS` or `PR_MANUALLY_MERGED` or `DRAFT_PULL_REQUEST_CREATION_FAILED` or `DRAFT_PULL_REQUEST_CREATION_BRANCH_NOT_INDEXED` or `CONFIGURATION_CHANGED` or `UNPROCESSABLE_PULL_REQUEST` or `PR_MANUALLY_DEQUEUED` or `STACK_PREDECESSOR_DEQUEUED` or `INTERMEDIATE_RESULTS_SKIPPED` or `CHECKS_RETRIED` or null | A dequeue code for when a pull request has been disembarked from the merge queue. |
| `queue-merge-started-at` | date-time or null | The time the pull request mergeability checks have started at. |
| `queue-name` | string or null | The name of the queue containing the pull request. |
| `queue-position` | integer | The position of the pull request in its queue if queued. The first pull request in the queue has position 0. The value is set to -1 if the pull request is not queued. |
| `queued-at` | date-time or null | The time the pull request was queued at for merge. |
| `removed-files` | list of string | The files that are removed by the pull request. |
| `repository-full-name` | string | The current repository full name (complete version with the organization name). |
| `repository-name` | string | The current repository name (short version without the organization name). |
| `review-requested` | list of string | The list of GitHub user or team login that were requested to review the pull request. Team logins are prefixed with the @ character. This only matches reviewers with `admin`, `write` or `maintain` permission on the repository. |
| `review-threads-resolved` | list of string | The list of ids associated to review threads that are marked as resolved by GitHub. |
| `review-threads-unresolved` | list of string | The list of ids associated to review threads that are NOT marked as resolved by GitHub. |
| `schedule` | string | The current time will be compared against this schedule to validate this attribute. |
| `scope` | list of string | The list of scopes associated with the pull request for merge queue batching. |
| `sender` | string | The GitHub login of the command author. |
| `sender-permission` | GitHubRepositoryPermission | The permission of the command author. |
| `title` | string | The title of the pull request. |
| `updated-at` | date-time | The time the pull request was updated at. |
| `updates` | list of PullRequestHeadShaHistoryDict | The list of updates done on an opened pull request. |

## Operators List

<table>
  <thead>
    <tr>
      <th>Operator Name</th>
      <th>Symbols</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Equal</td>

      <td>
        `=` or `:`
      </td>

      <td>This operator checks for strict equality. If the target attribute
      type is a list, each element of the list is compared against the value
      and the condition is true if **any** value matches.</td>
    </tr>

    <tr>
      <td>Not Equal</td>

      <td>
        `!=` or `≠`
      </td>

      <td>This operator checks for non equality. If the target attribute type
      is a list, each element of the list is compared against the value and
      the condition is true if no value matches.</td>
    </tr>

    <tr>
      <td>Match</td>

      <td>
        `~=`
      </td>

      <td>This operator checks for [regular
      expressions](/configuration/data-types#regular-expressions)
      matching. If the target attribute type is a list, each
      element of the list is matched against the value and the condition is
      true if any value matches.</td>
    </tr>

    <tr>
      <td>Glob</td>

      <td>
        `*=`
      </td>

      <td>This operator checks for matching path using [Unix-style pathname
      pattern expansion](/configuration/data-types/#globs).
      If the target attribute type is a list, each element of the list is
      matched against the value and the condition is true if any value matches.</td>
    </tr>

    <tr>
      <td>Greater Than or Equal</td>

      <td>
        `>=` or `≥`
      </td>

      <td>This operator checks for the value to be greater than or equal to the
      provided value. It's usually used to compare against the length of a
      list using the `#` prefix.</td>
    </tr>

    <tr>
      <td>Greater Than</td>

      <td>
        `>`
      </td>

      <td>This operator checks for the value to be greater than the provided
      value. It's usually used to compare against the length of a list using
      the `#` prefix.</td>
    </tr>

    <tr>
      <td>Lesser Than or Equal</td>

      <td>
        `<=` or `≤`
      </td>

      <td>This operator checks for the value to be lesser then or equal to the
      provided value. It's usually used to compare against the length of a
      list using the `#` prefix.</td>
    </tr>

    <tr>
      <td>Lesser Than</td>

      <td>
        `<`
      </td>

      <td>
        This operator checks for the value to be lesser than the provided value. It's
        usually used to compare against the length of a list using the `#` prefix.
      </td>
    </tr>
  </tbody>
</table>

### Operators on Lists

Most [operators](#operators-list) iterate over list attributes and return true
if **any** value matches.

For a pull request with labels `(bug, work-in-progress)`:

- `label = work-in-progress` is **true**.
- `label = enhancement` is **false**.
- `label != work-in-progress` is **false**.
- `label ~= ^work` is **true**.
- `-label ~= ^work` is **false** (negated with `-`).

### Examples with Operators

```yaml
# Match a specific milestone
- milestone = v1.0

# Fewer than 50 files changed
- "#files <= 50"

# Label is not "bug"
- label != bug
```

## Combining Conditions Using Logical Operators

Combine conditions with `and`, `or`, and `not`.

### The `and` Operator

Conditions on separate lines within the same rule are implicitly joined by
`and`. The `and` keyword can also be used explicitly to group conditions.

```yaml
name: Require reviews and CI
if:
  - base = main
success_conditions:
  - and:
    - "#approved-reviews-by >= 2"
    - "check-success = test job"
```

### The `or` Operator

```yaml
name: Require reviews or passing CI
if:
  - base = main
success_conditions:
  - or:
    - "#approved-reviews-by >= 2"
    - "check-success = test job"
```

### The `not` Operator

`not` negates a block of conditions, typically wrapping an `and` or `or`.

```yaml
name: Block merges missing requirements
if:
  - base = main
success_conditions:
  - not:
      and:
        - "#approved-reviews-by >= 2"
        - "check-success = test job"
```

## Testing and Debugging Conditions

### Use the Mergify Configuration Editor

The configuration editor evaluates your conditions against existing pull
requests without triggering actions.

1. Navigate to your [Mergify dashboard](https://dashboard.mergify.com).
2. Select the repository you want to test.
3. Click on the "Config Editor" tab.

<Image src={configEditorScreenshot} alt="Mergify Configuration Editor" />

### Analyze the Mergify Checks

Once your configuration is committed, Mergify evaluates conditions for each
pull request. To inspect the evaluation:

1. Navigate to the "Checks" tab of the pull request.
2. Look for the "Mergify" check in the list of checks.
3. Click on "Summary" to view the detailed Mergify report.

The report shows which rules were evaluated and whether each condition was met.

<Image src={checkSummaryScreenshot} alt="Mergify Check Summary" />