Writing Custom Merge Protection Rules

Rules 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 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. Two kinds of unmet condition wait rather than fail: one on a check run or commit status that has not finished, and one on a time attribute (schedule or current-datetime) whose window is not open yet. Anything else unmet fails the 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:

Each example below is one item of the merge_protections list.

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.