Why MergeGuard?

← Back to Home

The Problem

GitHub provides powerful primitives for code review—CODEOWNERS, branch protection rules, required status checks—but they’re intentionally static. Once you mark a check as required or set up branch protection, GitHub applies the same rules to every pull request, regardless of context.

This creates challenges:

🔴 Inflexible Review Requirements

  • Can’t require different reviewers based on what files changed
  • No way to scale approval requirements with PR size
  • CODEOWNERS is all-or-nothing; can’t do “at least one from team A AND team B”

💸 Expensive CI Costs

  • All required checks run on every PR, even when unnecessary
  • Can’t conditionally require expensive E2E tests based on file paths
  • Documentation changes trigger full test suites

🤖 Manual Bot Management

  • Dependabot/Renovate PRs need manual review even for patch updates
  • No native way to auto-approve trusted automated PRs
  • Stacked PRs require manual merge ordering

📊 Poor Signal-to-Noise

  • Important changes mixed with trivial updates
  • No way to fast-track emergency fixes
  • Teams spend review time on low-risk changes

The MergeGuard Solution

MergeGuard adds a policy-driven decision layer on top of GitHub’s native workflow. It evaluates pull request context—files changed, lines of code, author, labels, semver level—and dynamically decides:

  • ✅ Who needs to approve (teams, specific users, approval counts)
  • ✅ Which checks must pass (context-aware required checks)
  • ✅ Whether to auto-approve or auto-merge (for trusted changes)
  • ✅ Merge ordering (via PR dependency detection)

All configured in a single .github/mergeguard.yml file in your repository.

Why Not Just Use GitHub Native?

Challenge GitHub Native MergeGuard
Different approvers per path CODEOWNERS (static mapping) Dynamic rules with paths + teams
Conditional required checks All checks always required Context-aware: only require when paths match
Auto-approve bots Manual or GitHub Actions workaround Built-in autoApprove action
Scale reviews by PR size One-size-fits-all maxLocChanged condition + tiered approvals
Emergency fast-track Manually disable branch protection Priority-based rules with labels
PR dependencies Manual coordination Automatic detection via Depends on #123

How It Works

  1. GitHub webhooks trigger MergeGuard when PRs are opened, updated, or reviewed
  2. MergeGuard reads .github/mergeguard.yml from your repo
  3. Builds PR context: files changed, LOC, author, labels, approvals, dependencies
  4. Evaluates rules: matches conditions, calculates requirements
  5. Creates GitHub Check Run: shows what’s needed, blocks merge if unmet
  6. Executes actions: auto-approve, auto-merge (when configured)

Everything is deterministic and auditable via GitHub’s native Check Runs.

Key Benefits

🎯 Contextual Enforcement

Apply different policies based on what actually changed, not static file ownership.

💰 Reduce CI Costs

Only run expensive tests when relevant paths are modified. Skip CI entirely for docs-only changes.

⚡ Faster Merges

Auto-approve and auto-merge trusted changes (bots, small fixes) while protecting critical paths.

🔒 No Compromises

Use GitHub’s native merge guarantees—MergeGuard adds intelligence, not new approval surfaces.

📈 Scales with Your Team

Start simple, add complexity as needed. Rules are additive and transparent.

Real-World Examples

Before MergeGuard

❌ Dependabot patches need manual approval (even 1-line version bumps)
❌ Docs changes trigger 30min CI suite
❌ Infrastructure changes get same review as typo fixes
❌ Stacked PRs merged out of order, breaking main

After MergeGuard

rules:
  - name: "Dependabot patches"
    if:
      author: "dependabot[bot]"
      semverLevel: "patch"
    action:
      autoApprove: true
      autoMerge: true

  - name: "Docs only"
    if:
      paths: ["docs/**"]
    require:
      approvals: 1
    # No checks required!

  - name: "Infrastructure"
    if:
      paths: ["infra/**"]
    require:
      approvals: 2
      teams: ["platform-team", "security-team"]
      checks: ["terraform-validate", "security-scan"]

Result:

  • ✅ Patches merge automatically within minutes
  • ✅ Docs skip expensive CI, saving $$
  • ✅ Infra changes get proper oversight + specific checks
  • ✅ PR dependencies block merges until parents are merged

Next Steps

Ready to try MergeGuard?