Dependabot Auto-Merge Setup Guide - Automatically approve and merge Dependabot PRs (patch/minor updates only)

dependabot-auto-merge-setup.md

Dependabot Auto-Merge Setup Guide

This guide provides a complete setup for automatically approving and merging Dependabot pull requests using GitHub Actions.

Prerequisites

1. Dependabot already enabled and configured for your repository
2. Admin access to the repository

Files Required

Auto-Merge Workflow (.github/workflows/dependabot-auto-merge.yml)

name: Dependabot Auto-Merge

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: write
  pull-requests: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]'
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/fetch-metadata@v2
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"

      - name: Enable auto-merge for Dependabot PRs
        if: |
          steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
          steps.metadata.outputs.update-type == 'version-update:semver-minor'
        run: gh pr merge --auto --merge "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Approve PR
        if: |
          steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
          steps.metadata.outputs.update-type == 'version-update:semver-minor'
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Configuration Steps

Step 1: Enable Repository Auto-Merge Feature

Choose one of the following methods:

Option A: Using GitHub CLI (if installed)

gh repo edit --enable-auto-merge

Option B: Using GitHub Web Interface

1. Navigate to your repository on GitHub
2. Go to Settings → General
3. Scroll down to the "Pull Requests" section
4. Check the box for "Allow auto-merge"
5. Click Save changes

Step 2: Configure GitHub Actions Permissions

1. Navigate to your repository on GitHub
2. Go to Settings → Actions → General
3. Scroll down to Workflow permissions
4. Check the box for "Allow GitHub Actions to create and approve pull requests"
5. Click Save

Without this setting, the workflow will fail with the error:

GitHub Actions is not permitted to approve pull requests

How It Works

1. Dependabot creates a pull request for dependency updates
2. The workflow triggers when the PR is opened or updated
3. Metadata is fetched to ensure it's a valid Dependabot PR and check the update type
4. For patch and minor updates only:
   • Auto-merge is enabled on the PR (will merge when all checks pass)
   • The PR is automatically approved by GitHub Actions
   • The PR merges automatically once all required status checks pass
5. For major updates: The PR is created but requires manual review and approval

Security Note: Major version updates are excluded from auto-merge because they often contain breaking changes that require human review.

Customization Options

Update Types to Auto-Merge

Default (Recommended): Auto-merge patch and minor updates only (as shown above).

Alternative - Patch updates only (most conservative):

if: steps.metadata.outputs.update-type == 'version-update:semver-patch'

Alternative - All updates including major (not recommended):

# Remove the if condition entirely to auto-merge all updates
# WARNING: Major updates may contain breaking changes
- name: Enable auto-merge for Dependabot PRs
  run: gh pr merge --auto --merge "$PR_URL"

Additional Checks

Add more steps before auto-merge, such as:

• Running tests
• Security scans
• Build verification

Troubleshooting

Common Issues

1. "GitHub Actions is not permitted to approve pull requests"

   • Ensure Step 2 above is completed in repository settings

2. "Auto-merge is not enabled for this repository"

   • Complete Step 1 above using either CLI or web interface

3. PRs not auto-merging

   • Check that all required status checks are passing
   • Verify branch protection rules don't conflict

Verification

Check if auto-merge is enabled (requires GitHub CLI):

gh repo view --json autoMergeAllowed

Security Considerations

• Only auto-merges patch and minor updates - Major updates require manual review due to potential breaking changes
• This workflow only runs for Dependabot PRs (github.actor == 'dependabot[bot]')
• Uses built-in GITHUB_TOKEN with minimal required permissions
• Respects all existing branch protection rules and required status checks
• PRs still need to pass all configured checks before merging
• Major version updates will be created but not auto-approved, allowing for security review

References

• GitHub Docs: Automating Dependabot
• GitHub CLI Documentation