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)

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. Rules Are Evaluated

Each rule’s if conditions are checked against the PR context. All conditions must match (AND logic).

4. Priority Selection

If multiple rules match:

  • Only rules with the highest priority (lowest number) are enforced
  • Multiple rules with the same priority are all enforced
  • Default priority is 100

5. GitHub Check Run Created

MergeGuard creates/updates a Check Run showing:

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

6. 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

Validation

Before pushing your config, validate it locally:

yarn validate:config

For IDE validation, add this to the top of your YAML file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/MergeGuard/mergeguard-app/main/schema/mergeguard.schema.json

rules:
  - name: "..."

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

  • Check Run Details - Click the MergeGuard check to see evaluation details
  • Validation Errors - Run yarn validate:config for schema validation
  • GitHub Issues - Report bugs or request features