Merge gates: safe-to-merge checks for pull requests

Most teams already have a pile of checks on every pull request: the build, the tests, a linter, a security scanner, an AI review, a required approval. Each one answers a narrow question. None of them answers the question the person about to press merge is actually asking: is this safe to merge, and if not, what is left to do?

A merge gate answers that question. This guide explains what a merge gate is, what it should look at, how MergeHarbor’s works, and how to introduce one without blocking your team on day one.

Status checks are not a merge decision

A status check reports one fact. “Tests passed.” “Review posted, confidence 3 of 5.” “Two approvals.” Branch protection can require some of them, but the decision about whether everything together is good enough is left to whoever reads the page.

That leaves gaps that show up in incident reviews:

• The review flagged a major finding, but the review check passed because it only fails on critical ones, and nobody scrolled down.
• The linked ticket had three acceptance criteria and the change met two.
• A risky change to a migration had no tests for the changed function, but overall coverage did not drop.
• A finding was real enough that a generated test reproduced it, and the pull request merged anyway.

Each of these is visible somewhere. The point of a gate is to combine them into one verdict, with a reason, in the place where the merge happens.

What a merge gate is

A merge gate is a single check per commit that reads every signal you care about, applies your policy and reports one of a small number of verdicts. MergeHarbor’s has four:

• Ready to merge: every check in your policy passed.
• Ready with warnings: nothing blocks the merge, but some checks need a look.
• Blocked: something in your policy must be fixed first.
• Waiting for review: the latest commit is still being reviewed.

Next to the verdict sits a merge readiness score from 0 to 100 and a checklist, most important first, where every item says what to do: “Fix: refund amount is not validated”, “Meet criterion 2 of PAY-12”, “Add tests for Partial() in pay/refund.go”, “Get 1 more approval”.

The score is the weighted average of the measured signals, kept within the verdict’s range, so the number and the verdict always agree:

What the gate looks at

One rule matters a lot for trust: a signal that is not measured never blocks. If a repository has no coverage data, the checklist says coverage was not checked instead of failing the gate or silently passing it.

The gate is checked again whenever something changes: a new push, a finding resolved or dismissed, a review or proof run finishing, requirements or approvals changing, or the policy changing.

Policies and presets

Writing a policy from scratch is where most gate projects stall, so MergeHarbor starts from presets that you can then adjust:

Branch policies apply a different preset to some target branches. A common setup is Standard everywhere, Strict for main and Regulated for release/*. The first matching pattern wins.

Policies cascade like the rest of MergeHarbor’s settings: the organization’s policy, then a repository’s own policy, then .mergeharbor.yml. The organization can lock the policy so a repository cannot weaken it. Because configuration files are read from the pull request’s merge base, a pull request cannot loosen its own gate.

# .mergeharbor.yml
merge_gate:
  enabled: true
  mode: advisory # or enforce
  preset: standard # relaxed | standard | strict | regulated
  rules:
    required_approvals: 1
    min_coverage: 70
  branches:
    - pattern: "release/*"
      preset: regulated

Every rule you can change, such as block_severity, max_risk or proven_findings, is in the configuration reference.

Advisory and enforce

A gate that blocks merges before the team trusts it gets switched off. That is why advisory mode is the default: the gate reports its verdict and checklist but never fails the check.

Switch to enforce under Settings → Checks & gates → Merge gate when you want a failing verdict to fail the check. On its own that still does not stop anything; you also make the check required on your code host (next section). Advisory mode is also the right way to try a stricter policy: run it for a couple of weeks and see what it would have blocked.

Making it required on each code host

The gate appears as its own check, MergeHarbor / merge gate, next to the review check, which it never changes.

• GitHub: a check run with the checklist. Add MergeHarbor / merge gate as a required status check in branch protection or a ruleset. A warning shows as neutral and still lets the pull request merge. See AI code review for GitHub.
• GitLab: a commit status named MergeHarbor / merge gate. On GitLab Ultimate, add an external status check whose name contains “MergeHarbor” under Settings → Merge requests → Status checks; MergeHarbor answers it as passed or failed for each commit. See setting up AI code review on GitLab.
• Azure DevOps: add a branch policy requiring the status mergeharbor/merge-gate. See AI code review for Azure DevOps.
• Bitbucket and Gitea: require the MergeHarbor / merge gate build status or commit status. See AI code review for Bitbucket.

Merges started from MergeHarbor’s console, single or bulk, always respect the gate.

Overrides

Sometimes a blocked change has to ship: a hotfix during an incident, or a finding the team has decided to accept. A gate with no escape hatch gets bypassed in worse ways, such as an admin turning off branch protection.

People with the Override a blocked merge gate permission (owners and admins by default) can override the gate for one commit, with a reason, from the pull request or the merge dialog. The check then passes and says who overrode it and why, MergeHarbor comments on the pull request, and the override goes into the audit log. A new push is checked again, so an override does not carry forward. If your policy should not allow overrides at all, turn them off in the policy.

A rollout plan

A sequence that works for most teams:

1. Week 1–2: advisory, Standard preset. Turn the gate on for a few active repositories. Read the checklist on real pull requests. Look for verdicts that feel wrong, and for signals that are not measured yet.
2. Fix the inputs. If the review is noisy, the gate will be too. Tune strictness and rules first; see how to reduce false positives. Connect Jira or Linear if you want requirements checked.
3. Week 3: enforce on one branch. Switch to enforce, add a branch policy for main, and make the check required on the code host for that branch only.
4. Tighten where it matters. Add Strict or Regulated for release branches, or for repositories that handle payments or personal data. Lock the organization policy if repositories should not weaken it.
5. Review overrides monthly. Overrides with reasons are the best signal of where the policy and reality disagree.

If you need evidence for auditors, the gate pairs with compliance evidence, which records approvals, checks and resolved findings for every merged pull request.

Measuring whether it works

Insights → Risk → Merge gate shows, for merged pull requests, how many were ready, how many were blocked and then fixed before merging, how many were overridden, how many merged on the code host while blocked, and how many passed but were reverted later. It also lists what blocks merges most and the recent overrides with their reasons.

Two numbers deserve attention. “Blocked then fixed” is the gate doing its job. “Passed but reverted later” tells you what the policy is missing.

Which plan includes it

The merge gate is part of the Team plan and above. The 14-day trial is the Team plan, so you can try it on your own repositories before deciding. See pricing and what AI code review costs per developer.

Try it in advisory mode

Start a 14-day trial of the Team plan, with no card needed. Connect a repository, leave the merge gate in advisory mode, and read its checklist on your next ten pull requests before you decide whether to enforce it.

Further reading

• Merge gate, the reference page
• Merge gate feature overview
• How AI code review works
• AI code review for enterprises
• Setting up AI code review on GitLab merge requests
• AI code review for monorepos and large repositories