Auto-Approval & Auto-Merge

← Back to Features

Automatically approve and merge trusted changes like Dependabot patches, bot updates, or small documentation fixes.

Overview

Manual approval of low-risk PRs wastes reviewer time:

• Dependabot patch updates (1-line version bumps)
• Documentation typos
• Small automated fixes from bots
• Formatting/linting changes

MergeGuard’s auto-approval and auto-merge features eliminate this toil while maintaining safety through configurable requirements.

Auto-Approval

Automatically leave an approval when a rule matches.

Configuration

action:
  autoApprove: true

How It Works

1. Rule conditions match the PR
2. MergeGuard immediately leaves an approval review
3. Approval counts toward the required approval count
4. Other requirements (teams, users, checks) still apply

Example: Auto-Approve Small Changes

- name: "Small safe changes"
  if:
    maxLocChanged: 10
    excludePaths:
      - "infra/**"
      - "secrets/**"
  require:
    approvals: 1
  action:
    autoApprove: true

Result: MergeGuard auto-approves, satisfying the 1-approval requirement. PR can merge once checks pass.

Auto-Merge

Automatically merge the PR when all requirements are met.

Configuration

action:
  autoMerge:
    requireChecks: true    # Optional: require checks to pass (default: true)
    mergeMethod: "squash"  # Optional: merge method (default: repo setting)

Options

How It Works

1. Rule conditions match
2. Requirements are checked (approvals, teams, users, checks)
3. If requireChecks: true, waits for all checks to complete
4. Once all requirements satisfied, PR is automatically merged
5. Uses specified merge method (or repository default)

Example: Auto-Merge Dependabot Patches

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

Result:

1. Dependabot opens patch/minor update
2. MergeGuard auto-approves
3. Security scan runs
4. When security scan passes → auto-merge with squash

Use Cases with Examples

1. Fully Automated Dependabot

Auto-approve and auto-merge safe dependency updates:

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

Result: Patch updates merge automatically within minutes (after checks pass).

2. Graduated Dependabot Strategy

Different automation levels by semver:

rules:
  - name: "Dependabot patches - full auto"
    priority: 10
    if:
      author: "dependabot[bot]"
      semverLevel: "patch"
    require:
      checks: ["security-scan"]
    action:
      autoApprove: true
      autoMerge:
        requireChecks: true

  - name: "Dependabot minor - auto-approve only"
    priority: 20
    if:
      author: "dependabot[bot]"
      semverLevel: "minor"
    require:
      checks: ["security-scan", "integration-tests"]
    action:
      autoApprove: true
    # No auto-merge - needs manual merge

  - name: "Dependabot major - manual review"
    priority: 30
    if:
      author: "dependabot[bot]"
      semverLevel: "major"
    require:
      approvals: 2
      checks: ["security-scan", "integration-tests", "e2e-tests"]
    # No auto-approve or auto-merge

Result:

• Patches → fully automated
• Minor → auto-approved, manual merge
• Major → full manual review

3. Documentation Fast-Track

Auto-approve and merge docs-only changes:

- name: "Docs only"
  priority: 20
  if:
    paths: ["docs/**", "README.md"]
    excludePaths: ["src/**"]
    maxLocChanged: 100
  require:
    approvals: 1
  action:
    autoApprove: true
    autoMerge:
      requireChecks: false  # Skip waiting for checks
      mergeMethod: "squash"

Result: Small doc changes auto-approve and merge immediately (no check wait).

4. Renovate Bot with Security Gate

Auto-merge Renovate updates after security scan:

- name: "Renovate patches"
  if:
    author: "renovate[bot]"
    semverLevel: ["patch", "minor"]
  require:
    checks:
      - "snyk-scan"
      - "dependency-review"
  action:
    autoApprove: true
    autoMerge:
      requireChecks: true
      mergeMethod: "squash"

5. Emergency Hotfix Auto-Merge

Fast-track urgent fixes with minimal friction:

- name: "Emergency hotfix"
  priority: 5
  if:
    labels: ["hotfix", "urgent"]
  require:
    approvals: 1
    users: ["incident-commander"]
    checks: ["smoke-tests"]
  action:
    autoMerge:
      requireChecks: true
      mergeMethod: "merge"  # Preserve history for hotfixes

Result: Once incident commander approves and smoke tests pass → auto-merge.

6. Formatting/Linting PRs

Auto-merge automated formatting fixes:

- name: "Auto-formatting"
  if:
    author: "github-actions[bot]"
    labels: ["auto-format"]
    maxLocChanged: 500
  require:
    checks: ["lint"]
  action:
    autoApprove: true
    autoMerge:
      requireChecks: true
      mergeMethod: "squash"

7. Stacked PRs with Auto-Merge

Auto-merge child PRs once parent merges (with dependencies):

- name: "Stacked PR automation"
  if:
    labels: ["stack"]
  require:
    approvals: 1
    checks: ["unit-tests"]
  action:
    autoMerge:
      requireChecks: true

Add to PR description:

Depends on #123

Result: Once parent #123 merges and requirements are met → child auto-merges.

Safety Considerations

Auto-Approve Is Safe When…

✅ Combined with path exclusions:

if:
  maxLocChanged: 10
  excludePaths: ["infra/**", "secrets/**"]

✅ Author is trusted:

if:
  author: "dependabot[bot]"

✅ Other requirements still apply:

require:
  checks: ["security-scan"]

Auto-Merge Is Safe When…

✅ Checks are required:

action:
  autoMerge:
    requireChecks: true

✅ Approvals are required:

require:
  approvals: 1
  teams: ["platform-team"]

✅ Conditions are narrow:

if:
  author: "dependabot[bot]"
  semverLevel: "patch"
  paths: ["package.json"]

Merge Methods

merge (Merge Commit)

Creates a merge commit preserving all individual commits.

Use when:

• You want full history
• Working with hotfixes
• Tracking feature branches

action:
  autoMerge:
    mergeMethod: "merge"

squash (Squash and Merge)

Combines all commits into a single commit.

Use when:

• You want clean history
• PR has many small commits
• Working with bot updates

action:
  autoMerge:
    mergeMethod: "squash"

Default for: Dependabot, Renovate, automated PRs.

rebase (Rebase and Merge)

Rebases commits onto base branch.

Use when:

• You want linear history
• Avoiding merge commits
• Working with feature branches

action:
  autoMerge:
    mergeMethod: "rebase"

Note: Fails if rebase conflicts exist.

Skipping Check Wait

Set requireChecks: false to merge without waiting for checks:

action:
  autoMerge:
    requireChecks: false
    mergeMethod: "squash"

Use when:

• Documentation changes don’t need CI
• Urgent fixes can’t wait for slow checks
• Checks are informational only

Caution: This bypasses normal CI gates. Use sparingly.

Best Practices

1. Start Conservative, Relax Over Time

Begin with auto-approve only, add auto-merge later:

# Week 1: Auto-approve only
action:
  autoApprove: true

# Week 2: Add auto-merge after observing behavior
action:
  autoApprove: true
  autoMerge:
    requireChecks: true

2. Always Require Security Checks

Even for bots, keep security validation:

require:
  checks: ["security-scan", "dependency-audit"]

3. Use Path Exclusions

Never auto-merge changes to critical paths:

if:
  excludePaths:
    - "infra/**"
    - "secrets/**"
    - ".github/workflows/**"

4. Combine with Size Limits

Cap auto-merge at reasonable LOC:

if:
  maxLocChanged: 50
  author: "dependabot[bot]"

5. Monitor Auto-Merge Activity

Track which PRs auto-merge in your metrics. If something seems wrong, tighten conditions.

Troubleshooting

Auto-Approve Not Working

Check:

1. MergeGuard has pull_requests: write permission
2. Rule actually matched (check MergeGuard Check Run)
3. Approval isn’t being dismissed by another automation

Auto-Merge Not Working

Check:

1. All requirements are actually satisfied (approvals, teams, users, checks)
2. If requireChecks: true, all checks have passed
3. Branch protection allows the merge method
4. Repository has auto-merge enabled
5. No merge conflicts exist

Debug: Look at MergeGuard Check Run details—it shows why merge is blocked.

Auto-Merge Too Aggressive

Tighten conditions:

if:
  author: "dependabot[bot]"
  semverLevel: "patch"      # Only patches, not minor/major
  maxLocChanged: 10         # Very small changes only
  paths: ["package.json"]   # Specific files only

Related Features

• Conditional Approvals - Dynamic approval requirements
• Context-Aware Checks - Required checks per rule
• PR Dependencies - Auto-merge with dependency blocking