How to Auto-Merge a Pull Request When Checks Pass

gh pr merge --auto queues the PR to merge itself the moment required checks and reviews are satisfied.

Turn on auto-merge in the repo settings, then call gh pr merge --auto from a workflow (or the UI). GitHub waits for required checks and approvals, then merges with your chosen strategy.

Steps

• Enable Allow auto-merge in repository settings.
• Require the checks you care about in branch protection.
• Call gh pr merge --auto with a merge strategy flag.

Terminal

# Queue this PR to merge once required checks pass
gh pr merge 123 --auto --squash

# From a workflow, target the current PR
gh pr merge "$PR_URL" --auto --merge --delete-branch

Workflow

on:
  pull_request:
    types: [labeled]
permissions:
  contents: write
  pull-requests: write
jobs:
  enable-automerge:
    if: github.event.label.name == 'automerge'
    runs-on: ubuntu-latest
    steps:
      - run: gh pr merge "${{ github.event.pull_request.number }}" --auto --squash
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gotchas

• Auto-merge requires branch protection with at least one required check; without it the flag errors.
• A dismissed review or a new required check re-blocks the queued merge until satisfied again.

Related guides