heydeer

GitHub auto-merge: set it up and fix PRs that won’t merge

· · 9 min read

GitHub auto-merge lets you say “merge this when it’s ready” and walk away. The setting itself takes ten seconds. Most of the work, and most of the confusion when a pull request sits there with auto-merge on, lives in the branch rules that define “ready.”

GitHub auto-merge merges a pull request automatically once every required review and status check passes. Turn on Allow auto-merge under the repository’s Settings → General → Pull Requests, require reviews or checks with a branch protection rule or ruleset, then select Enable auto-merge on a pull request or run gh pr merge --auto.

Turn on auto-merge for a repository

Auto-merge is off until a repository admin allows it. Open the repository’s Settings, stay on General, scroll to Pull Requests and select Allow auto-merge. From then on, anyone with write access can switch it on for an individual pull request.

That alone changes nothing you can see, and this surprises people. GitHub shows Enable auto-merge only on pull requests that can’t merge yet. On a branch with no requirements, every pull request can merge right now, so the button never appears. Auto-merge needs something to wait for.

Define what “ready to merge” means

The requirements come from a branch protection rule or a ruleset on the target branch, usually main. Rulesets are the newer of the two and can stack, where only one branch protection rule applies to a branch at a time; for auto-merge they offer the same building blocks:

  • Require a pull request before merging, with a number of required approvals. Approvals count when they come from people with write access, or from a code owner if you also require code owner review.
  • Require status checks to pass, naming the exact checks. A check only appears in the picker after it has completed successfully in the repository in the past seven days, so run your CI once before setting this up.
  • Require branches to be up to date before merging (strict checks). The pull request has to contain the latest base branch, which means more CI runs on a busy repository. A merge queue is the better fix for that, covered below.
  • Dismiss stale pull request approvals when new commits are pushed, so an approval covers the code that actually merges, and optionally Require approval of the most recent reviewable push, which asks for an approval from someone other than the last person to push.

The combination you pick decides what auto-merge really means on your repository. With one required approval and CI checks, it means “merge when a reviewer has signed off and the build is green.” With checks only, it means “merge when the build is green,” which is a reasonable rule for some repositories and a risky one for others.

Auto merge a pull request on GitHub

In the browser, open the pull request, optionally pick a merge method from the dropdown in the merge box, select Enable auto-merge, edit the commit message if you chose merge or squash, and select Confirm auto-merge. The merge box then says the pull request will merge automatically when all requirements are met. People with write access and the pull request’s author can turn it off again with Disable auto-merge.

gh pr merge --auto

From a terminal, or from a coding agent that just opened the pull request, the GitHub CLI does the same thing:

# Squash-merge this branch's pull request once every requirement is met
gh pr merge --auto --squash --delete-branch

# A specific pull request, and only if nobody has pushed since you looked
gh pr merge 482 --auto --squash --match-head-commit 3f9c2e1

# Changed your mind
gh pr merge 482 --disable-auto

Without a number, gh pr merge picks the pull request for the current branch. --match-head-commit is worth knowing: it makes the merge conditional on the head still being the commit you expect, so a late push can’t ride along on your decision.

Why auto-merge waits, or turns itself off

A pull request with auto-merge on and no merge is waiting for something. The merge box names what, but some causes are less obvious than others.

A required check that never reports

This is the most common one. If a workflow is skipped by a paths filter, a branch filter or a skip instruction in the commit message, its checks stay pending and the pull request shows “Waiting for status to be reported” forever. A job skipped by an if: condition behaves differently: it reports success. So the fix is to let the workflow always run and decide inside it whether the expensive job is needed:

name: ci
on:
  pull_request:

jobs:
  changes:
    runs-on: ubuntu-slim
    outputs:
      code: ${{ steps.diff.outputs.code }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: diff
        run: |
          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -qvE '^docs/|\.md$'; then
            echo "code=true" >> "$GITHUB_OUTPUT"
          else
            echo "code=false" >> "$GITHUB_OUTPUT"
          fi

  test:
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: make test

A related trap: when a job that a required job needs fails, the required job is skipped and may not block the merge. Use if: always() on required jobs with dependencies, and fail them explicitly when a dependency failed. Path filters are also a cost question, which our GitHub Actions pricing guide covers.

An approval that went stale

With stale approvals dismissed, every push after the approval takes it away, including clicking Update branch. Auto-merge then waits for a new approval. This is the setting working as intended, but it catches teams who expected the original approval to carry the pull request through.

A branch that has to be up to date

With strict status checks, every merge to main puts the other open pull requests behind again. They wait until their branches are updated and CI passes on the new code.

Conflicts

A pull request with merge conflicts can’t merge, auto-merge or not. Someone has to resolve them first; our guide to resolving merge conflicts on GitHub walks through it.

When GitHub switches auto-merge off

GitHub disables auto-merge when someone without write access pushes to the head branch or when the base branch is changed. That is a safety rule: an outside contributor shouldn’t be able to add commits to something a maintainer already agreed to merge. Re-enable it after you have looked at the new commits.

Merged, but nothing deployed

If a workflow merges with the built-in GITHUB_TOKEN, the resulting push to main doesn’t start new workflow runs. GitHub does this to prevent recursive runs, and it means deploy workflows that listen for push stay silent. When the merge has to trigger them, give the merge step a GitHub App installation token or a personal access token instead.

How to auto approve pull requests

If your rules require an approval, auto-merge waits for one. For some pull requests, such as a dependency patch with green CI, a person reading the diff adds little. GitHub supports approving those from a workflow, within limits.

GitHub auto approve with GITHUB_TOKEN

A workflow can approve with gh pr review --approve using GITHUB_TOKEN only if the repository allows it: under Settings → Actions → General → Workflow permissions, turn on Allow GitHub Actions to create and approve pull requests. It is off by default for new repositories in personal accounts, and organization repositories inherit the organization’s setting, which an organization admin may have locked.

The Dependabot pattern

GitHub documents a workflow that reads Dependabot’s metadata and acts on it. This version approves and enables auto-merge for everything except major version bumps, which still wait for a person:

name: Dependabot auto-merge
on: pull_request

permissions:
  contents: write
  pull-requests: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: github.event.pull_request.user.login == 'dependabot[bot]'
    steps:
      - id: metadata
        uses: dependabot/fetch-metadata@v3
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

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

      - name: Enable auto-merge
        if: steps.metadata.outputs.update-type != 'version-update:semver-major'
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The if on the job limits it to pull requests Dependabot opened, and pull requests from forks get a read-only GITHUB_TOKEN, so an outside contributor can’t use this workflow to approve their own change. Keep Require status checks to pass on as well: the approval says the change is acceptable, and the checks say it works.

A workflow can approve a pull request with gh pr review --approve and GITHUB_TOKEN only when the repository setting Allow GitHub Actions to create and approve pull requests is on. Paired with gh pr merge --auto and required status checks, it merges Dependabot updates you have chosen to trust once CI passes.

A blanket auto-approve for every pull request is a different thing. It removes the review requirement while keeping its badge. If that is what you want, lower the required approvals instead; if it isn’t, the approval needs to come from something that actually read the change.

Where a merge queue fits

On a branch that many people merge into, strict up-to-date checks turn into a queue of rebases. A merge queue replaces them: after a pull request passes its own checks, the queue tests it on top of the latest base branch and the pull requests ahead of it, and merges the group when those checks pass. On a branch that requires a merge queue, Merge when ready enables auto-merge for a pull request that can’t join the queue yet, even if Allow auto-merge is off, and gh pr merge does the same.

Two details matter. Your workflows must also trigger on merge_group, or the queue waits for checks that never run:

on:
  pull_request:
  merge_group:

And GITHUB_TOKEN can’t add pull requests to a merge queue, so the Dependabot workflow above needs a GitHub App token or a personal access token for its merge step on such a branch.

Approval that comes from a review

The auto-approve patterns above decide from metadata: who opened the pull request, what kind of version bump it is. HeyDeer, an AI code review agent for GitHub, approves from the review itself. With Automatic approval on, HeyDeer approves a pull request when a complete review leaves nothing for a person to decide, and every review states a risk level (low, medium or high) and why. You choose which risk levels it may approve, low and medium by default, and whether Low-severity findings may remain.

Some pull requests always wait for a person. HeyDeer never approves pull requests from authors without write access, such as outside contributors and bots, whatever the settings allow. It leaves changes to the guidance it reads, such as AGENTS.md, CLAUDE.md, repository checks and skills, to a person. And when a later review doesn’t approve, it dismisses its earlier approval.

Put that next to GitHub auto-merge and the loop closes. The recommended setup requires one approval with stale approvals dismissed, requires the HeyDeer Review check next to your CI, and has the agent that opened the pull request run gh pr merge --auto --squash. A pull request then merges when CI passes and the review approves. For pull requests that need work first, Autopilot fixes review findings, failing checks and merge conflicts round after round until the pull request is ready to merge or needs you, and auto-merge takes it from there.

HeyDeer approves a pull request as the HeyDeer GitHub App when a complete review leaves nothing for a person to decide, within the risk levels you allow. With one required approval, the HeyDeer Review check required and GitHub auto-merge on, a pull request merges once CI passes and HeyDeer approves.

Sources

  1. GitHub Docs: Automatically merging a pull request
  2. GitHub Docs: Managing auto-merge for pull requests in your repository
  3. GitHub Docs: About protected branches
  4. GitHub Docs: Troubleshooting required status checks
  5. GitHub CLI manual: gh pr merge
  6. GitHub Docs: Managing GitHub Actions settings for a repository
  7. GitHub Docs: GITHUB_TOKEN
  8. GitHub Docs: Automating Dependabot with GitHub Actions
  9. GitHub Docs: Managing a merge queue
  10. GitHub Docs: Merging a pull request with a merge queue

Frequently asked questions

How do I enable auto-merge on GitHub?

GitHub auto-merge is enabled in two places. A repository admin turns on Allow auto-merge under Settings → General → Pull Requests. Then someone with write access selects Enable auto-merge in a pull request’s merge box, picks a merge method and confirms, or runs gh pr merge --auto with --merge, --squash or --rebase.

Why is the Enable auto-merge button missing?

The Enable auto-merge button appears only on pull requests that can’t merge yet, for example because a branch rule requires an approving review or a passing status check that hasn’t arrived. If the branch has no requirements, or they are already met, GitHub shows the regular merge button instead. The repository must also have Allow auto-merge turned on.

Why didn’t my pull request auto-merge?

A pull request with auto-merge on waits until every requirement passes. The usual blockers are a missing approval, a required check that never reports because its workflow was skipped by a path or branch filter, an approval dismissed as stale after a new push, a branch that must be up to date with the base branch, or a merge conflict. A push from someone without write access also turns auto-merge off.

Can GitHub Actions approve a pull request?

GitHub Actions can approve a pull request with GITHUB_TOKEN only when Allow GitHub Actions to create and approve pull requests is on under Settings → Actions → General → Workflow permissions. It is off by default for new repositories in personal accounts; organization repositories inherit the organization’s setting. The workflow then runs gh pr review --approve.

How do I auto-merge Dependabot pull requests?

Dependabot pull requests auto-merge with a workflow that runs on pull_request, checks that the author is dependabot[bot], reads the update type with dependabot/fetch-metadata, and runs gh pr merge --auto for the updates you accept, such as patch versions. Require your CI checks on the target branch so nothing merges on a red build.

What does gh pr merge --auto do?

gh pr merge --auto enables auto-merge on a pull request from the command line, so GitHub merges it once the required reviews and checks pass. Combine it with --squash, --merge or --rebase for the method, --delete-branch to clean up, and --match-head-commit to refuse the merge if someone pushes in the meantime. gh pr merge --disable-auto turns it off.

What is the difference between auto-merge and a merge queue?

Auto-merge waits for one pull request’s requirements and then merges it. A merge queue tests each pull request together with the latest base branch and the pull requests ahead of it before merging, so a busy branch never breaks from two changes that pass separately. On a branch with a merge queue, Merge when ready enables auto-merge and adds the pull request to the queue once it qualifies.

Start with your first PR.

Free plan. No credit card required.

Get started free