Auto-Approval & Auto-Merge

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.

Merge queue note: Merge queues sit at the very end of the merge workflow. MergeGuard still evaluates the pull request and can describe what would normally auto-approve or auto-merge, but on merge-queue branches the queue owns the final merge step and MergeGuard reports a compatible queue check instead of directly merging.

Auto-Approval

Automatically leave an approval when a rule matches.

Configuration

action:
  autoApprove: true

How It Works

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

On merge-queue branches, MergeGuard keeps review policy visible in the PR check and comment, but direct automation may be intentionally deferred because the queue controls the final merge stage.

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

Option	Type	Default	Description
`requireChecks`	boolean	`true`	Wait for all required checks to pass before merging
`mergeMethod`	string	(repo default)	Merge method: `merge`, `squash`, or `rebase`

How It Works

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

On branches that require GitHub merge queue, MergeGuard does not perform the final direct merge itself. Instead, it evaluates the PR normally, keeps the policy visible, and publishes a companion MergeGuard check on the queue’s merge_group commit so the PR can continue through the queue.

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:

Dependabot opens patch/minor update
MergeGuard auto-approves
Security scan runs
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).

If the target branch uses merge queue, think of this as “automated up to the queue.” MergeGuard still evaluates the PR and required checks, and GitHub’s queue performs the actual merge at the final stage.

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.

On merge-queue branches, the same dependency logic still applies, but the final merge is performed by the queue rather than by a direct MergeGuard merge call.

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:

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

Auto-Merge Not Working

Check:

All requirements are actually satisfied (approvals, teams, users, checks)
If requireChecks: true, all checks have passed
Branch protection allows the merge method
Repository has auto-merge enabled
No merge conflicts exist
If the branch uses merge queue, remember that GitHub’s queue performs the final merge and MergeGuard only keeps the PR and merge_group checks compatible

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

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

← Back to Features

Next: PR Dependencies →

Auto-Approval & Auto-Merge

Overview

Auto-Approval

Configuration

How It Works

Example: Auto-Approve Small Changes

Auto-Merge

Configuration

Options

How It Works

Example: Auto-Merge Dependabot Patches

Use Cases with Examples

1. Fully Automated Dependabot

2. Graduated Dependabot Strategy

3. Documentation Fast-Track

4. Renovate Bot with Security Gate

5. Emergency Hotfix Auto-Merge

6. Formatting/Linting PRs

7. Stacked PRs with Auto-Merge

Safety Considerations

Auto-Approve Is Safe When…

Auto-Merge Is Safe When…

Merge Methods

merge (Merge Commit)

squash (Squash and Merge)

rebase (Rebase and Merge)

Skipping Check Wait

Best Practices

1. Start Conservative, Relax Over Time

2. Always Require Security Checks

3. Use Path Exclusions

4. Combine with Size Limits

5. Monitor Auto-Merge Activity

Troubleshooting

Auto-Approve Not Working

Auto-Merge Not Working

Auto-Merge Too Aggressive

Related Features

`merge` (Merge Commit)

`squash` (Squash and Merge)

`rebase` (Rebase and Merge)