---
title: Writing Your First Rule
description: Automate your first workflow with Mergify Workflow Automation
---
import { Image } from "astro:assets"
import configEditorScreenshot from "../../images/workflow/writing-your-first-rule/config-editor.png"
import summaryScreenshot from "../../images/workflow/writing-your-first-rule/summary.png"
## Understanding The Configuration File
The Mergify configuration file consists of two primary components: rules and
actions. Rules define the conditions under which specific actions should be
triggered, while actions specify the automated tasks to be performed on the
pull requests. By combining rules and actions, you can create a powerful and
flexible automation process tailored to your specific requirements.
In the following sections, we will explore how to define rules using conditions
and how to set up actions for various use cases, such as merging, labeling, and
assigning pull requests.
Mergify streamlines your pull request process by applying rules you define. To
utilize Mergify, you must create a configuration file within each repository
where you want to enable its functionality.
Place the configuration file in the root directory of the repository, and name
it one of the following: `.mergify.yml`, `.mergify/config.yml`, or
`.github/mergify.yml`.
The [configuration file](/configuration/file-format) relies on
[YAML](https://yaml.org/), a simple and human-readable data file format. For
comprehensive details on the configuration file format, please refer to the
[configuration file format](/configuration/file-format) section.
## The Rules
To create a rule in the Mergify configuration file, you must specify the
following three essential components:
- **Rule name**: A unique identifier for each rule, allowing you to easily
manage and organize your automation workflow.
- **Conditions**: A list of criteria that the pull request must fulfill for the
rule to apply, such as the status of checks, labels, or approvals.
- **Actions**: A list of automated tasks executed when the conditions are met,
such as merging, labeling, or assigning the pull request.
By carefully crafting your rules, you can build a powerful and customized pull
request automation process that aligns with your project's needs.
### Writing Your First Rule
To get started with creating your first rule in the Mergify configuration file,
follow these steps:
1. **Choose a unique name for your rule**: This will help you identify and
manage the rule within your configuration file.
2. **Define the conditions**: List the criteria that a pull request must meet
for the rule to apply. Conditions are written in YAML syntax and may include
factors like the pull request's status, labels, or number of approvals.
3. **Specify the actions**: Determine the tasks that should be executed
automatically when the conditions are met, such as merging the pull request,
adding labels, or assigning reviewers.
Here's a sample rule that demonstrates the process:
```yaml
pull_request_rules:
- name: Automatic merge when CI passes and approved
conditions:
- "#approved-reviews-by >= 2"
- check-success = your-ci-name
- base = main
actions:
merge:
```
In this example, the rule named "Automatic merge when CI passes and approved"
will be triggered when the following conditions are met:
- The pull request has at least 2 approved reviews.
- The *your-ci-name* check passes.
- The base branch for the pull request is *main*.
When these conditions are satisfied, Mergify will perform the following action:
- Automatically merge the pull request.
### Using the Configuration Editor
The [Mergify dashboard](https://dashboard.mergify.com) provides a built-in
configuration editor to help you create, edit, and test your configuration file
easily. The editor allows you to write and validate your Mergify configuration
without leaving the dashboard, ensuring that your rules are correctly formatted
and functional.
To use the configuration editor, follow these steps:
1. **Navigate to the [Mergify dashboard](https://dashboard.mergify.com)**: Log
in to your Mergify account and access your dashboard.
2. **Open the configuration editor**: Locate and click on the *Configuration
Editor* link or button within the dashboard.
3. **Edit your configuration**: Use the textarea provided to write or modify
your Mergify configuration file. The editor supports YAML syntax and
provides a convenient way to define your rules, conditions, and actions.
4. **Specify a pull request number**: To validate your configuration, enter a
pull request number in the designated field. This allows the editor to test
your configuration against a real pull request to ensure it works as
expected.
5. **Validate your configuration**: As you edit your configuration, the editor
automatically checks for syntax and formatting errors. Ensure that your
configuration is valid before proceeding.
6. **Create a pull request to save your configuration**: Once you have finished
editing and validating your configuration, click the "Create Pull Request"
button. This will generate a new pull request with your updated
configuration file, allowing you to review the changes before merging them
into your repository.
By using the configuration editor, you can easily manage your Mergify rules and
ensure a smooth automation process for your pull requests.
## Understanding Mergify Rule Conclusions
Mergify continuously evaluates your rules whenever a pull request is updated or
modified. When a rule's conditions are met, Mergify triggers the corresponding
actions. To help users understand what is happening with their rules and why
certain actions are or are not triggered, Mergify provides a
summary of its rules
evaluation within a Check, similar to other CI systems.
### Mergify Summary
The Mergify Summary is a concise report of the rules evaluation for each pull
request. It is displayed as a Check within the GitHub UI, making it easy for you
to review the results and understand the state of your rules and actions.
To view the Mergify Summary, follow these steps:
1. **Open the pull request**: Navigate to the pull request you want to review
within the GitHub UI.
2. **Access the Checks tab**: Click on the "Checks" tab located near the top of
the pull request page.
3. **Locate the Mergify Summary**: Scroll through the list of Checks to find
the one named "Mergify". Click on the "Details" link to view the full
summary.
The Mergify Summary provides information on:
- The rules that were evaluated.
- The conditions that were met or not met.
- The actions that were triggered or not triggered.
By reviewing the Mergify Summary, you can gain insight into the behavior of your
Mergify configuration and make any necessary adjustments to your rules and
actions.