Quickstart Guide

← Back to Home

Get MergeGuard running in your repository in under 5 minutes.

Step 1: Install the GitHub App

  1. Go to MergeGuard on GitHub Marketplace
  2. Click “Install”
  3. Select the repositories you want to enable
  4. Authorize the app

Required Permissions:

  • contents: write (for auto-merge)
  • pull_requests: write (for comments and reviews)
  • checks: write (for Check Runs)
  • statuses: read (for commit status checks like Terraform Cloud)
  • members: read (for team-based approval rules)

Step 2: Create Configuration File

Add .github/mergeguard.yml to your repository:

rules:
  - name: "Default policy"
    require:
      approvals: 1

Commit and push this file to your repository.

Step 3: Open a Pull Request

MergeGuard will automatically:

  1. Evaluate the PR against your rules
  2. Create a GitHub Check Run showing requirements
  3. Update the check as approvals/changes happen

That’s it! You now have basic PR automation running.

Understanding the Flow

1. GitHub Triggers MergeGuard

When a PR is opened, updated, or reviewed, GitHub sends a webhook event to MergeGuard.

2. MergeGuard Builds Context

Collects information about the PR:

  • Files changed (paths)
  • Lines of code added/deleted
  • PR author
  • Labels
  • Existing approvals
  • Semver level (for Dependabot PRs)
  • Dependencies (via Depends on #123 syntax)

3. Rule Evaluation Process

MergeGuard evaluates rules using a priority-based system:

┌─────────────────────────────────────────┐
│  1. Evaluate ALL rules                  │
│     ↓                                   │
│     Check each rule's `if` conditions   │
│     (all conditions must match = AND)   │
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│  2. Group matching rules by priority    │
│     ↓                                   │
│     Rule A (priority: 10) ✓ matched     │
│     Rule B (priority: 50) ✓ matched     │
│     Rule C (priority: 100) ✓ matched    │
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│  3. Select highest-priority group       │
│     ↓                                   │
│     Enforce: Rule A (priority 10)       │
│     Ignore: Rules B & C (lower priority)│
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│  4. If multiple rules share top priority│
│     ↓                                   │
│     ALL rules in that group are enforced│
│     (requirements are combined)         │
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│  5. GitHub Check Run shows decision     │
│     ↓                                   │
│     - Which rules matched & apply       │
│     - Requirements that must be met     │
│     - Current status                    │
└─────────────────────────────────────────┘

Key Points:

  • Lower number = higher priority (priority 10 beats priority 100)
  • Only the highest-priority matching rules are enforced
  • Multiple rules with the same top priority are all enforced together
  • Default priority is 100 if not specified
  • The readiness message reflects this final decision

Example:

rules:
  - name: "Emergency hotfix"
    priority: 10
    if:
      labels: ["hotfix"]
    require:
      approvals: 1

  - name: "Infrastructure"
    priority: 50
    if:
      paths: ["infra/**"]
    require:
      approvals: 2

  - name: "Default"
    priority: 100
    require:
      approvals: 2

If a PR has both hotfix label AND changes to infra/**:

  • ✅ Both “Emergency hotfix” (10) and “Infrastructure” (50) match
  • ✅ Only “Emergency hotfix” (10) is enforced (highest priority)
  • ❌ “Infrastructure” (50) and “Default” (100) are ignored

4. GitHub Check Run Created

MergeGuard creates/updates a Check Run showing:

  • Which rules matched and are being enforced
  • What requirements are needed
  • Current approval status
  • Which checks must pass

5. Actions Execute

If configured:

  • autoApprove: MergeGuard leaves an approval
  • autoMerge: When requirements are met, PR is merged

Rule Structure Basics

Every rule has four optional sections:

- name: "Rule name"          # Required
  description: "Why this rule exists"  # Optional but recommended
  priority: 50               # Optional (default: 100, lower = higher priority)
  
  if:                        # Conditions: when does this rule apply?
    maxLocChanged: 100
    paths: ["src/**"]
    excludePaths: ["test/**"]
    author: "dependabot[bot]"
    semverLevel: "patch"
    labels: ["urgent"]
  
  require:                   # Requirements: what must be satisfied?
    approvals: 2
    teams: ["platform-team"]
    users: ["tech-lead"]
    checks: ["unit-tests", "security-scan"]
  
  action:                    # Actions: what should happen automatically?
    autoApprove: true
    autoMerge:
      requireChecks: true
      mergeMethod: "squash"

Key Points:

  • if section: all conditions must match (AND logic)
  • require section: all requirements must be satisfied
  • action section: executed when rule matches and requirements are met

Common Starter Configurations

Fast-Track Small Changes

- name: "Small changes"
  if:
    maxLocChanged: 10
    excludePaths:
      - "infra/**"
      - ".github/workflows/**"
  require:
    approvals: 1
  action:
    autoApprove: true

Protect Critical Paths

- name: "Infrastructure changes"
  priority: 10
  if:
    paths:
      - "infra/**"
      - ".github/workflows/**"
  require:
    approvals: 2
    teams: ["platform-team"]
    checks:
      - "terraform-validate"
      - "security-scan"

Auto-Merge Dependabot Patches

- name: "Dependabot patches"
  if:
    author: "dependabot[bot]"
    semverLevel: ["patch", "minor"]
  require:
    checks: ["security-scan"]
  action:
    autoApprove: true
    autoMerge:
      requireChecks: true
      mergeMethod: "squash"

Skip CI for Documentation

- name: "Documentation only"
  if:
    paths: ["docs/**"]
    excludePaths: ["src/**"]
  require:
    approvals: 1
  # No checks required - saves CI costs!

Combined Example

rules:
  # High priority: Emergency fixes
  - name: "Emergency hotfix"
    priority: 10
    if:
      labels: ["hotfix"]
    require:
      approvals: 1
      users: ["incident-commander"]
    action:
      autoMerge:
        requireChecks: true

  # Medium priority: Infrastructure
  - name: "Infrastructure"
    priority: 50
    if:
      paths: ["infra/**"]
    require:
      approvals: 2
      teams: ["platform-team", "security-team"]

  # Default: Everything else
  - name: "Default policy"
    priority: 100
    require:
      approvals: 2

What Happens When…

A Rule Matches

✅ MergeGuard creates a Check Run showing requirements
✅ If autoApprove is set, an approval is added
✅ When requirements are met and autoMerge is set, PR merges

No Rules Match

⚠️ MergeGuard creates a Check Run with status “No matching rules”
⚠️ PR is not blocked but has no specific requirements enforced

Multiple Rules Match (Same Priority)

✅ All matching rules with the highest priority are enforced
✅ Requirements are combined (all must be satisfied)

Multiple Rules Match (Different Priorities)

✅ Only rules with the highest priority (lowest number) are enforced
✅ Lower priority rules are ignored

Next Steps

Now that you have the basics:

  1. Explore Features - Learn about all available capabilities:
  2. Start Simple - Begin with a default rule, add complexity as needed
  3. Test Incrementally - Add one rule at a time and observe behavior
  4. Monitor Effectiveness - Track which rules match most often

Getting Help