---
title: Mergify Configuration File
description: Everything you need to know about Mergify configuration file
---
The Mergify configuration file is an essential component of using our platform
effectively. This document will provide a comprehensive overview of the file,
including its name, format, and the data structure schema.
## Configuration File Name
Mergify applies the following rule to find and use its configuration:
- It reads the file named `.mergify.yml`, or, as a fallback,
`.mergify/config.yml` or `.github/mergify.yml` from the repository root
directory.
- It reads the file from the default repository branch configured on GitHub —
usually `main`.
- It can extends the configuration by another configuration using the keyword
`extends` — see ["extending the configuration
file"](#extending-configuration-files).
## File Format
The configuration file uses the [YAML](https://yaml.org/) format, which is both
human-readable and machine-parsable. YAML is easy to read and edit, making it a
popular choice for configuration files.
The file main type is a dictionary and each key of the dictionary configures a
different aspect of Mergify:
{/* FIXME: add link to a better page than writing your first rule? */}
- [`pull_request_rules`](#pull-request-rules) configures [Automation
Workflow](/workflow/);
- [`merge_protections`](#merge-protections) and
[`merge_protections_settings`](#merge-protections) configures [Merge
Protections](/merge-protections/);
- [`queue_rules`](#queue-rules) configures the [Merge
Queue](/merge-queue);
- [`merge_queue`](#merge-queue) configures option for the [Merge
Queue](/merge-queue);
- [`priority_rules`](#priority-rules) configures the [priorities for the Merge
Queue](/merge-queue/priority);
- [`commands_restrictions`](/commands/restrictions) configures who is able to
run commands;
- [`defaults`](#defaults) allows to configure default options for various
actions;
- [`shared`](#shared) allows to [define any YAML payload that can be used using
YAML anchors](/configuration/sharing#sharing-configuration-sections);
- [`extends`](#extends) allows to [extend the
configuration](/configuration/sharing#extending-configuration-files)
file by importing another configuration file.
### Pull Request Rules
The top-level key `pull_request_rules` allows to automate your workflow by
writing rules that execute actions. It must be a list of dictionary with the
following keys:
| 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. |
Example:
```yaml
pull_request_rules:
- name: add label when author is jd
description: jd needs his own label because reasons
conditions:
- author = jd
actions:
label:
add:
- jd
```
### Merge Protections
The top-level key `merge_protections` allows to protect your merge by adding a
list of rules that must match before allowing the pull request to be merged.
| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `description` | string or null | `null` | A description of the rule |
| `if` | List of conditions | | The conditions to check before applying the rule |
| `name` | string | | The name of the rule |
| `success_conditions` | List of conditions | | The conditions to check to validate the rule |
The top-level key `merge_protections_settings` allows to configure the
behavior of Merge Protections
| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `post_comment` | boolean | `true` | Whether to post merge protection status comments on pull requests |
| `reporting_method` | `check-runs` or `deployments` | `"check-runs"` | The merge protection reporting method |
### Merge Queue
The top-level key `merge_queue` allows to configure certain aspect of the merge
[merge queue](/merge-queue).
| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `dequeued_label` | string or null | `"dequeued"` | The label to add on pull requests when they are removed from the merge queue. |
| `max_parallel_checks` | integer | `5` | The maximum number of speculative checks allowed to run at the same time. Setting this value to 1 disables speculative checks. |
| `mode` | `serial` or `parallel` | `"serial"` | Defines how the merge queue schedules pull requests. - `serial`: PRs are tested cumulatively. - `parallel`: PRs whose scopes don't overlap are tested in parallel. |
| `queued_label` | string or null | `"queued"` | The label to add on pull requests when they are added to the merge queue. |
| `reset_on_external_merge` | `never` or `always` | `"always"` | Defines the behavior of the merge queue when something is merged outside of the queue. "always": The queue is reset when an external merge is detected. All queued pull requests are re-evaluated to ensure correctness based on the new base branch state. "never": The queue remains unchanged. It does not reset or re-evaluate based on the external merge. |
| `skip_intermediate_results` | boolean | `false` | Allow PRs to merge even if their own speculative check fails, as long as a later downstream check including them passes and schedule conditions are valid. |
| `status_comments` | `all` or `outcomes` or `none` | `"all"` | Controls the level of status comments posted on pull requests in the queue. - `all`: Post comments for all queue events (entering queue, CI progress, outcomes). - `outcomes`: Only post comments for final outcomes (merged or dequeued with failure reason). - `none`: Do not post any comments for queue status. |
### Queue Rules
The top-level key `queue_rules` allows to define the rules that reign over your
[merge queue](/merge-queue).
| Key name | Value type | Default | Description | Status |
| --- | --- | --- | --- | --- |
| `allow_inplace_checks` | boolean | `true` | Deprecated: this value is computed automatically. In-place checks are enabled only when: - `max_parallel_checks == 1` - every queue has `batch_size == 1` - every queue CI is single-step (no extra `merge_conditions`; either empty or identical to `queue_conditions`) | deprecated |
| `allow_queue_branch_edit` | boolean | `false` | When creating a branch for a queue, if the commits of this branch are edited by an entity external to Mergify, Mergify dequeues all pull requests embarked in the branch and report the issue as a failure. If set to `true`, Mergify will allow such modifications and trust the content of the branch. Make sure only Mergify and your external application are allowed to edit these branches. | |
| `autoqueue` | boolean | `false` | When set to true, automatically add a pull request to the queue when it matches the queue conditions. When false, the pull request must be manually queued. | |
| `batch_max_failure_resolution_attempts` | integer or null | `null` | The number of attempts to resolve a batch failure before dequeueing pull requests. By default, Mergify will attempt to resolve a batch failure by splitting the batch multiple times until it finds the root cause of the failure. You can stop this process earlier by limiting the number of resolution attempts. Setting this to 0 will dequeue all the pull requests from a batch when a batch fails. | |
| `batch_max_wait_time` | duration | `"30 seconds"` | The maximum amount of time to wait for additional pull requests before processing a batch that hasn't reached `batch_size`. The timer starts when the first pull request enters the batch. If `batch_size` is reached before this time expires, the batch processes immediately. This does not enforce a minimum delay between batches. | |
| `batch_size` | integer | `1` | The maximum number of pull requests per speculative check in the queue. Must be between 1 and 128. | |
| `branch_protection_injection_mode` | `queue` or `merge` or `none` | `"queue"` | Branch protections conditions injection mode to use. - `queue` will inject branch protections conditions as required conditions for queuing and merging pull requests. - `merge` will inject branch protections conditions as required conditions only for merging pull requests. - `none` will disable branch protections. This mode is supported only on queues using a `merge_bot_account` with admin rights. | |
| `checks_timeout` | duration or null | `null` | The amount of time the merge queue waits for pending checks to return before dequeueing pull requests. This cannot be less than 60 seconds. | |
| `commit_message_template` | template or null | `null` | Template to use as the commit message when using the merge or squash merge method. | |
| `draft_bot_account` | template or null | `null` | Mergify can impersonate a GitHub user to create its draft pull requests. If no `draft_bot_account` is set, Mergify creates the draft pull request itself. The user account must have already been logged in Mergify dashboard once and have admin, write or maintain permission. | |
| `max_checks_retries` | integer | `0` | Number of times Mergify will retry failed CI checks before removing the pull request from the queue. On each retry, the draft pull request is recreated to trigger a fresh CI run. This is useful for handling flaky CI. When set to a value greater than 0, in-place checks are disabled and a draft pull request is always created. Set to 0 (default) to disable retries. | |
| `merge_bot_account` | template or null | `null` | Mergify can impersonate a GitHub user to merge pull requests. If no `merge_bot_account` is set, Mergify merges the pull request itself. The user account **must** have already been logged in Mergify dashboard once and have **write** or **maintain** permission. | |
| `merge_conditions` | List of conditions | | The list of conditions to match to get the queued pull request merged. In case of draft pull request, the merge conditions for checks are evaluated against the temporary pull request instead of the original one. | |
| `merge_method` | `merge` or `rebase` or `squash` or `fast-forward` or `merge-batch` or null | `null` | Merge method to use. If no value is set, Mergify uses the first authorized method available in the repository configuration. Additionally, `merge-batch` merges the draft pull request prepared by the merge queue using a merge commit. This requires `batch_size > 1`. | |
| `name` | string | | | |
| `queue_branch_merge_method` | `fast-forward` or null | `null` | If set to `fast-forward`, Mergify will merge the draft pull request instead of merging the original pull request that has been checked. This only works when `merge_method` is set to `merge`. | deprecated |
| `queue_branch_prefix` | template | `"mergify/merge-queue/"` | Prefix for the merge queue branch name | |
| `queue_conditions` | List of conditions | | The list of conditions that needs to match to queue the pull request. | |
| `update_bot_account` | template or null | `null` | For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. If no `update_bot_account` is set, Mergify uses the pull request author instead. The user account **must** have already been logged in Mergify dashboard once. This option overrides the value defined in the queue rules section of the configuration. | |
| `update_method` | `rebase` or `merge` or null | `null` | Method to use to update the pull request with its base branch when the check is done in place. Possible values: - `merge` to merge the base branch into the pull request. - `rebase` to rebase the pull request against its base branch. When `null`, defaults to `merge` except if `merge_method` is `fast-forward` then it defaults to `rebase`. | |
### Priority Rules
The top-level key `priority rules` allows to define the rules that will determine
which [priority](/merge-queue/priority) a pull request has when entering your merge queue.
| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `allow_checks_interruption` | boolean | `true` | Allow interrupting the ongoing checks when the pull request entering the queue has a higher priority than the queued one(s). If set to false, a pull request with higher priority will be inserted just after the pull requests that have checks running. |
| `conditions` | List of conditions | | The list of conditions that needs to match to assign priority to the pull request. |
| `name` | string | | Name of the rule. |
| `priority` | `high` or `medium` or `low` or integer | `"medium"` | The priority of the pull request. |
### Defaults
The `defaults` section provides a means to set configuration values that act as
fallbacks for:
- Actions executed by both [pull request rules](/workflow/) and [commands](/commands)
- Configuration options for [queue rules](/merge-queue/)
Instead of defining the same options repeatedly for different rules, you can specify
them once in the defaults section. If a particular option is directly defined under
`pull_request_rules` or `queue_rules`, it will take precedence; otherwise, the system
resorts to the values defined in the `defaults` section.
```yaml
defaults:
actions:
comment:
bot_account: Autobot
queue_rule:
batch_size: 10
pull_request_rules:
- name: comment with default
conditions:
- label = comment
actions:
comment:
message: I 💙 Mergify
queue_rules:
- name: default
- name: default with smaller batch
batch_size: 2
```
This configuration is equivalent to:
```yaml
pull_request_rules:
- name: comment with default
conditions:
- label = comment
actions:
comment:
message: I 💙 Mergify
bot_account: Autobot
queue_rules:
- name: default
batch_size: 10
- name: default with smaller batch
batch_size: 2
```
In the example, the `bot_account` value is taken from the `defaults` section,
simplifying the `pull_request_rules` and ensuring consistent behavior across
different rules.
The same behavior applies for the `batch_size` option of the `queue_rules`, the
default value of `10` gets applied to the queue rule `default` but not for the
queue rule `default with smaller batch`, because it already has `batch_size: 2`.
### Shared
You can store anything in the `shared` key. Its main purpose is to provide a
place to put redundant YAML anchors. See
[Sharing](/configuration/sharing#sharing-configuration-sections).
### Extends
Mergify offers a feature to extend your configuration file by incorporating
settings from another repository, aiding in consistency and reducing
duplication. This is achieved by using the `extends` keyword at the top of your
configuration file and specifying the source repository. See [Extending
Configuration Files](/configuration/sharing#extending-configuration-files).
## JSON Schema Specification
For those interested in a more detailed and machine-readable description of the
Mergify configuration file format, a [JSON Schema](https://json-schema.org/)
specification is available. This specification can help you understand the
structure of the configuration file and can be used to generate client
libraries, server stubs, or API documentation.
You can find the JSON
Schema specification for the Mergify configuration here.
## Validation and Troubleshooting
When working with Mergify's configuration file, it's essential to validate and
troubleshoot any issues that may arise. Ensuring that your configuration file
is error-free and well-structured can help prevent unexpected behavior and
maintain a smooth workflow.
### Validation
To validate your Mergify configuration file, you can use Mergify's built-in
validation tool. Whenever you push a change to the configuration file, Mergify
will automatically validate the configuration and report any errors or warnings
in the "Checks" tab of your pull request.
If there are any issues with your configuration file, you will receive a
detailed description of the problem and guidance on how to fix it. Be sure to
address any errors or warnings to ensure optimal performance and avoid
potential issues.
### Validate Locally With Pre-Commit
To catch issues before pushing, you can validate your configuration locally
using [Mergify's pre-commit hook](https://github.com/Mergifyio/mergify-pre-commit). Add this to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/Mergifyio/mergify-pre-commit
rev: 1.0.0
hooks:
- id: validate-mergify-config
```
### Troubleshooting
If you encounter issues or unexpected behavior with your Mergify configuration
file, consider the following troubleshooting steps:
1. Double-check the file name and location: ensure that your configuration file
is correctly named (e.g., `.mergify.yml`) and is located in the right place.
See [Configuration File Name](#configuration-file-name) for details.
2. Verify the YAML syntax: confirm that your configuration file follows the
proper YAML syntax, including correct indentation, spacing, and structure.
3. Review your rules and conditions: Make sure that your rules and conditions
are correctly defined and accurately reflect your intended workflow.
4. Check for conflicting rules: examine your rules for any conflicts or
overlapping conditions that could cause unintended behavior.
5. Consult Mergify's documentation: refer to Mergify's documentation for
guidance on creating and managing your configuration file, as well as
understanding the various features and options available to you.
By following these troubleshooting steps, you can effectively identify and
resolve any issues with your Mergify configuration file, ensuring a smooth and
efficient automation process for your repository.
## Validating with the CLI
The [Mergify CLI](/cli) can check your configuration file locally before you
push, catching errors without waiting for a round-trip to GitHub.
### Validate
Check your configuration against the Mergify schema:
```bash
mergify config validate
```
This catches syntax errors, invalid keys, and type mismatches. It reads
`.mergify.yml`, `.mergify/config.yml`, or `.github/mergify.yml` from the
current directory.
### Simulate
Test your rules against an existing pull request without applying any actions:
```bash
mergify config simulate https://github.com/owner/repo/pull/142
```
Shows which rules would match and what actions Mergify would take. Useful for
testing rule changes before merging your configuration update.