Introduction

Dependabot auto-merge workflows often fail even when the pull request itself is valid and tests are green. The reason is that GitHub treats Dependabot-triggered automation differently from a normal maintainer-triggered workflow. The token permissions are narrower, branch protection still applies, and the chosen workflow event can determine whether the job has enough authority to approve or merge the PR.

Symptoms

  • Dependabot PRs fail with Resource not accessible by integration
  • The auto-merge step can read the PR but cannot approve or merge it
  • The workflow succeeds for maintainer-created PRs and fails only for Dependabot
  • Branch protection keeps the PR blocked even after automation runs

Common Causes

  • The workflow token lacks pull-requests: write or contents: write
  • The workflow uses an event context that does not grant enough permission for the merge action
  • Branch protection requires approvals or checks the workflow is not satisfying
  • The repository expects auto-merge, but the workflow never enables it for the PR

Step-by-Step Fix

  1. 1.Grant explicit token permissions
  2. 2.Auto-merge and approval workflows should declare the permissions they need instead of relying on the default token profile.
yaml
permissions:
  pull-requests: write
  contents: write
  1. 1.Use the right workflow event for Dependabot automation
  2. 2.Many repositories use pull_request_target for approval and merge workflows because it runs with repository context, but that choice requires careful security review.
yaml
on:
  pull_request_target:
  1. 1.Make branch protection and merge logic agree
  2. 2.If branch protection requires approvals, status checks, or update-to-date behavior, the workflow must satisfy those requirements before merge can succeed.
  3. 3.Restrict auto-merge to safe update classes
  4. 4.Auto-merging patch and minor updates is a different risk profile than auto-merging majors. Use metadata to limit scope deliberately.

Prevention

  • Declare token permissions explicitly in Dependabot workflows
  • Keep branch protection rules aligned with the workflow’s actual approval and merge steps
  • Auto-merge only the update types your team is willing to trust automatically
  • Review pull_request_target usage carefully before giving merge authority to automation