Configuring Auto-Merge

Auto-merge is a rules-based system that evaluates every analyzed pull request against a set of configurable criteria. The flow works like this:

1. 1PR analysis completes (via risk scoring)
2. 2The worker evaluates all seven auto-merge rules
3. 3If every rule passes → MergeShield schedules a merge job with a configurable cooldown
4. 4After the cooldown → the worker re-checks all criteria and merges via the GitHub API

The evaluation is conservative by design. All seven rules must pass for auto-merge to proceed. If any single rule blocks, the merge is not scheduled and the block reasons are recorded in the dashboard.

Auto-merge decisions are recorded with full details about which rules passed, which blocked, and why. You can view these on the PR detail page in the Auto-Merge tab. If an approval workflow is also configured and an approval is pending, auto-merge evaluation is skipped until the approval is resolved.

Auto-merge is disabled by default for all repositories. To enable it:

1. 1Navigate to the repository detail page in the dashboard (Repositories → click on a repo)
2. 2Scroll to the Auto-Merge Configuration section
3. 3Toggle the Enabled switch

When you first enable auto-merge, the default rules provide a conservative starting point:

• Max risk score: 30
• Min trust level: medium
• Max files changed: 50
• Require all CI checks: true
• Cooldown: 5 minutes
• Merge method: squash

These defaults are designed to only auto-merge clearly low-risk changes from agents with a reasonable track record. You can adjust any threshold to match your team's risk tolerance. Changes take effect immediately for subsequent analyses.

PRs that have already been analyzed will not be retroactively re-evaluated unless you manually trigger a re-evaluation from the PR detail page.

There are seven configurable rules in the auto-merge system:

• maxRiskScore (default: 30) — Maximum overall risk score a PR can have. Any PR scoring above this is blocked.
• minTrustLevel (default: medium) — Minimum trust level required. PRs from humans or undetected agents are subject to the humanPRCheck toggle.
• maxFilesChanged (default: 50) — Blocks PRs that modify more than the specified number of files, as large PRs are harder to verify automatically.
• excludePatterns — Glob patterns for file paths that should block auto-merge when modified (e.g., *.lock, migrations/*).
• requireAllChecks — Ensures all GitHub status checks and CI workflows must pass. MergeShield filters out its own statuses (mergeshield/*) to prevent self-blocking.
• enabled — Master toggle for whether auto-merge is active for the repository.
• mergeMethod — Set to squash, merge, or rebase to match your team's preferred Git workflow.

The cooldown period (default: 5 minutes, configurable 0–1440 minutes) adds a safety buffer between the merge decision and the actual merge.

During this window, team members can:

• Review the PR and cancel by closing it
• Push new commits — this invalidates the original merge decision because the headSha changes, requiring a fresh analysis and evaluation

After the cooldown expires, the auto-merge worker performs a second check of all criteria. This catches cases where conditions changed during the cooldown — CI checks may have failed, the trust score might have been updated, or an admin might have changed the configuration. The merge only proceeds if all rules still pass.

The merge is performed via the GitHub API using your configured merge method. If GitHub rejects the merge (merge conflicts, branch protection failures, concurrent updates), the decision is recorded as failed with the specific error details.

If you're not ready to enable auto-merge but want to understand how your rules would behave, the dashboard provides a dry-run preview.

When auto-merge is disabled for a repository, the PR detail page shows a simulated evaluation of what would happen if auto-merge were enabled with the current settings. The preview evaluates all seven rules against the PR's actual analysis data and shows:

• Which rules would pass ✓
• Which rules would block ✗
• The specific reason for each block

This lets you fine-tune thresholds before going live. For example, you might discover that your maxRiskScore needs to be raised from 30 to 40 because your AI agents frequently produce scores in the 25–35 range for legitimate low-risk changes.

The dry-run is computed entirely on the client side using analysis data and repository settings already loaded on the page. It does not make any API calls or create merge decisions in the database.

Auto-merge and approval workflows work together to create a tiered governance system. When both are enabled on a repository, the pipeline works like this:

1. 1PR analysis completes with a risk score
2. 2Approval evaluation runs first — if the risk score exceeds the approval threshold, a pending approval is created and auto-merge is paused
3. 3A reviewer approves the PR — from MergeShield or GitHub (both sync automatically)
4. 4On approval, auto-merge re-evaluates all seven rules with the latest data
5. 5If all rules pass → PR is merged with the configured cooldown

This creates a natural separation: low-risk PRs below the approval threshold are auto-merged immediately, while higher-risk PRs require human approval before auto-merge proceeds.

For example, with approval riskThreshold: 40 and auto-merge maxRiskScore: 60:

• Score 0–39: Auto-merges immediately (no approval needed)
• Score 40–60: Requires approval, then auto-merges after approval
• Score 61+: Requires approval, and auto-merge blocks (risk too high) — must use force merge or merge manually on GitHub

For the strongest enforcement, add mergeshield/approval as a required status check in GitHub branch protection. See the Maximum Governance Setup section for step-by-step instructions.