Writing Custom Merge Protection Rules
Define fine-grained success conditions evaluated by the Mergify Merge Protections check.
- Keys
-
success_conditionsif
Rule structure
Section titled Rule structureRules live under the merge_protections key in your configuration file. Each
rule needs name, if, and success_conditions; description is optional:
merge_protections: - name: <human readable name> description: <purpose / context> if: # list (YAML array) of conditions activating the rule - <condition> success_conditions: # list of conditions that must all pass for success - <condition>Write them by hand, or build them in the dashboard, which commits the same YAML to your configuration file through a pull request.
Both condition lists also accept true in place of a list, the same shorthand
for “no conditions” that workflow rules use: a rule
meant to apply to every pull request writes if: true instead of a condition
that always matches.
Evaluation:
-
If all
ifconditions are true, the rule becomes active. -
If active, all
success_conditionsmust be true for the rule to succeed. -
A failing active rule fails the overall
Mergify Merge Protectionscheck. -
An active rule that is only waiting leaves that check pending instead of failing it. An unmet condition waits when it can still turn true on its own, with nothing asked of you: one on a check run or commit status that has not finished, or on a time attribute (
scheduleorcurrent-datetime) whose window has not opened yet. One that cannot turn true on its own fails the check.
Inactive rules are ignored (not shown as failing).
Condition language
Section titled Condition languageThe same rich expression system used by Workflow Automation applies. See:
Common condition patterns:
| Goal | Example Condition |
|---|---|
| Target specific branch | base = main |
| Enforce title prefix | title ~= ^feat: |
| Require label | label = security-reviewed |
| Match file changes | files ~= ^src/ |
| Require author team | author = @security-team |
| Require check success | check-success = ci/build |
Examples
Section titled ExamplesEach example below is one item of the merge_protections list.
Conventional Commits
Section titled Conventional Commitsname: Conventional commitsif: - base = mainsuccess_conditions: - 'title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?:'Require design review for UI changes
Section titled Require design review for UI changesname: UI Design Reviewif: - files ~= ^ui/success_conditions: - label = design-approvedEnsure security label if touching auth code
Section titled Ensure security label if touching auth codename: Auth Security Reviewif: - files ~= ^auth/success_conditions: - label = security-reviewedKeys on this page
-
merge_list or trueprotections[]. success_ conditions -
merge_list or trueprotections[]. if
Was this page helpful?
Thanks for your feedback!