Merge Protections

GitHub’s branch protection and rulesets are foundational, but their customizations are somewhat limited.

For more advanced or specific scenarios, Mergify’s Merge Protections can step in, enabling you to define nuanced conditions that cater to your project’s unique needs. This flexibility means you can design branch protection rules that the native system simply can’t handle.

1. Advanced Conditions: Mergify supports a vast array of conditions, which means you can create extremely specific rules based on any of the pull request metadata.

2. Dependencies: Leverage dependencies between pull requests.

3. Scheduled Merges: Make sure merges are done on the right time.

4. Freeze: Schedule one-time or recurring total or partial freeze for your repository.

Merge protections can be configured directly from your dashboard by clicking on the Merge Protections link in the sidebar.

Once enabled on your repository, Mergify will post a check entitled Mergify Merge Protections on your pull requests. You need to ensure this checks is required in your branch protection settings or in your rulesets.

Once Mergify Merge Protections is required in your repository rules, it will be marked as enforced in your GitHub checks and will prevent any pull request to be merged if does not match your conditions.

Mergify will also post an update as a comment on pull requests, including details of the matching protections.

Mergify provides multiple built-in protections that are available out-of-the-box.

The Depends-On protection prevents pull request to be merged if the dependent pull requests are not yet merged.

To use this feature, you simply need to list pull request dependencies in the pull request body using one of the following format:

Depends-On: #123
Depends-On: https://github.com/myorg/myrepo/pull/123
Depends-On: myorg/myrepo#123

A pull request can depends on any other pull request if both those conditions are matched:

• Mergify is enabled on the target repository;
• The repository is part of the same organization.

You can use the Merge-After pull request header to merge a pull request after a certain date using our timestamp format.

This built-in rule prevents users from merging breaking configuration changes. If Mergify detects a change in the configuration, the pull request will need to validate the Configuration changed check.

This rule is automatically added to your repository when you enable Merge Protections.

You can add any new rule by clicking on the New Rule button and using a template or writing from scratch.

The format of the rules is as follow:

name: <name of your rule>
description: <description of your rule>
if: <list of conditions that the pull request needs to match to see the rule applied>
success_conditions: <list of conditions that needs to match for the check to be a success>

You can refer to the format of the conditions for more details.

For example, to check that your pull request targeting the main branch follows the conventional commit convention you can write:

name: Enforce conventional commit
description: Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
if:
  - base = main
success_conditions:
  - "title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?:"

If you want to prevent pull request to be merged during certain periods, you can create scheduled freezes on your repository.

You can also freeze your repository instantly by clicking on “Freeze Merges Now”.