--- title: Mergify Configuration File description: Everything you need to know about Mergify configuration file --- import DownloadLink from '../../../components/DownloadLink.astro'; import { Image } from "astro:assets" import configCheckScreenshot from "../../images/configuration/config-check.png" import OptionsTable from '../../../components/Tables/OptionsTable'; 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: 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. The top-level key `merge_protections_settings` allows to configure the behavior of Merge Protections ### Merge Queue The top-level key `merge_queue` allows to configure certain aspect of the merge [merge queue](/merge-queue). ### Queue Rules The top-level key `queue_rules` allows to define the rules that reign over your [merge queue](/merge-queue). ### 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. ### 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. Mergify configuration check 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.