Merge Preflight Docs
Start Policies Integrations Billing Troubleshooting
Configuration

Repository policies

Create `.mergepreflight.yml`

  1. Add `.mergepreflight.yml` at the repository root.
  2. Set `schema_version: 1`.
  3. Add ordered `rules`. Each rule has an `id`, optional `enabled`, and optional `configuration`.
  4. Commit the file to the default branch or the PR branch being evaluated.

If the file is missing, Merge Preflight uses a valid empty policy. Draft pull requests are skipped until they are ready for review.

Policy categories

The hosted policy editor is generated from policy metadata. The same policy ids and configuration keys work in repository file policies.

Category Policies
Pull request hygiene require_pull_request_label, pull_request_title_pattern, maximum_pull_request_size, require_issue_reference
Source control conventions branch_name_pattern, commit_message_pattern
Release safety freeze_window, require_changelog, require_no_active_deployment_freeze
External systems require_linked_jira_issue_status, require_linked_linear_issue_state, block_unrelated_pr_during_sentry_critical, allow_linked_hotfix_during_incident

Use GitHub branch protection or GitHub rulesets for required reviews, CODEOWNERS approval, and required status checks. Merge Preflight no longer exposes GitHub-native approval or check policies.

YAML shortcuts

For common policy families, top-level YAML sections keep repository policy files readable while resolving to the same rule definitions used by the hosted editor.

branch_name_policy:
  patterns:
    - '^feature/[A-Z]+-\d+-.*$'
commit_message_policy:
  patterns:
    - '^[A-Z]+-\d+ .+$'
  scope: all_commits
pull_request_title_policy:
  patterns:
    - '^[A-Z]+-\d+: .+$'
pull_request_size_policy:
  max_changed_lines: 1000
  max_changed_files: 25
  max_commits: 10
freeze_windows:
  timezone: America/New_York
  periods:
    - days: [MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY]
      start: "18:00"
      end: "09:00"
changelog_policy:
  branches:
    - '^release/.*$'
  required_files:
    - CHANGELOG.md

GitHub status and check output

For GitHub, Merge Preflight publishes a Check Run. Passing evaluations report success. Blocking findings report failure with blocker messages and remediation text. Warning-only evaluations do not block merging.

The admin evaluation detail page shows the input summary, rule results, findings, external object references, and provider status/comment references for repositories you can view.

Use bypass

Emergency bypass is audited. On GitHub pull request comments, use `@mergepreflight bypass reason for the override`. Repository admins and configured allowlist users may bypass. Repositories can also allow provider-confirmed target-branch merge users; generic repository write permission is not enough.

Bypass events appear in `/admin/bypasses` with actor, reason, PR reference, head SHA, timestamp, and blockers at the time of bypass.

Examples

Minimal GitHub policy Jira policy Linear policy Sentry incident-mode policy

Policy behavior notes

  • require_pull_request_label accepts label or labels and compares labels case-insensitively.
  • pull_request_title_pattern, branch_name_pattern, and commit_message_pattern use regular expressions. Invalid regular expressions fail policy validation before evaluation.
  • maximum_pull_request_size can limit changed lines, changed files, commit count, or any combination of those limits.
  • freeze_window uses structured freeze_windows periods with IANA timezones and local HH:mm start/end times.
  • require_changelog runs only on branches matching configured branch regexes and accepts exact paths or glob patterns.
  • Jira, Linear, and Sentry policies require configured integrations with the capability shown in the hosted policy editor.

Most rules support mode: warn when a finding should be visible without blocking the merge.