View as Markdown

Writing Custom Merge Protection Rules

Define fine-grained success conditions evaluated by the Mergify Merge Protections check.

Keys
success_conditionsif

Rules live under the merge_protections key in your configuration file. Each rule needs name, if, and success_conditions; description is optional:

.mergify.ymlyaml
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 if conditions are true, the rule becomes active.

  • If active, all success_conditions must be true for the rule to succeed.

  • A failing active rule fails the overall Mergify Merge Protections check.

  • 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 (schedule or current-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).

Rule Rule Ignored Ignored Rule->Ignored  an if condition  is false Active Active Rule->Active  every if condition  is true Unmet Not met Active->Unmet  one is not Success Succeeds Active->Success  every success  condition is true Pending Pending Unmet->Pending  it can still turn  true on its own Failure Fails Unmet->Failure  it cannot
A rule whose if conditions all match is active, and its success conditions decide whether it succeeds, waits or fails. A rule that does not match is ignored.

The 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

Each example below is one item of the merge_protections list.

yaml
name: Conventional commits
if:
- base = main
success_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 changes
yaml
name: UI Design Review
if:
- files ~= ^ui/
success_conditions:
- label = design-approved

Ensure security label if touching auth code

Section titled Ensure security label if touching auth code
yaml
name: Auth Security Review
if:
- files ~= ^auth/
success_conditions:
- label = security-reviewed

Keys on this page

  • merge_protections[].success_conditions list or true
  • merge_protections[].if list or true

Was this page helpful?