Writing Custom Merge Protection Rules

Each rule consists of:

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>

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.

Inactive rules are ignored (not shown as failing).

The same rich expression system used by Workflow Automation applies. See:

• Conditions Reference
• Data Types

Common condition patterns:

name: Conventional commits
if:
  - base = main
success_conditions:
  - "title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?:"

name: UI Design Review
if:
  - files ~= "^ui/"
success_conditions:
  - label = design-approved

name: Auth Security Review
if:
  - files ~= ^auth/
success_conditions:
  - label = security-reviewed

• Keep rules focused; split unrelated concerns.
• Prefer positive success conditions over large negative patterns.
• Use naming conventions for clarity (e.g. Prefix groups: Title /, Security /).
• Periodically prune obsolete rules to reduce evaluation noise.

Combine Merge Protections with Workflow Automation (e.g., auto-labeling) so that protections depend on labels automatically applied from code context.