Auto-merge is a GitHub feature that marks a PR "merge when all conditions are met." It is useful when:
- You received a review with requested changes, pushed a fix, and are now waiting for CI to go green. Instead of sitting at your computer you enable auto-merge and move on to another task.
- You have an open PR that needs an approve from a busy reviewer. Enable auto-merge, and when the reviewer approves the PR merges on its own.
Enabling
Via CLI:
gh pr merge 123 --auto --squash --delete-branch
A strategy flag (--squash, --rebase, --merge) is required:
auto-merge needs to know which strategy to use.
Via UI: on the PR page, click "Enable auto-merge" (next to the regular merge button). A strategy dropdown appears; select one.
Merge conditions
Auto-merge fires when all of the following are satisfied:
- Required reviews are in (if branch-protection has "Require approvals" set).
- Required status checks are green (if "Require status checks to pass" is set).
- If "Require branches to be up to date" is set, the branch is current with the target.
- All conversations are resolved (if "Require conversation resolution" is set).
- For CODEOWNERS paths, an approve from the owner is present (if "Require review from Code Owners" is set).
If any condition is not met, auto-merge waits.
Cancelling
Remove auto-merge with:
gh pr merge 123 --disable-auto
Or click "Disable auto-merge" in the UI.
Auto-merge also cancels automatically if:
- Someone submits a Request Changes review.
- Someone force-pushes to the PR branch (the existing approve is invalidated).
- A required check fails.
Pitfalls
- Auto-merge must be enabled in repo Settings. Settings -> General -> Pull Requests -> "Allow auto-merge". It is off by default.
- Without required conditions auto-merge fires immediately. That is effectively a regular merge. It is only useful when there is something to wait for.
- On public repos auto-merge may be unavailable to the author if branch protection requires approvals and the author cannot approve their own PR.
- Auto-merge does not rebase against main. If "Require branches to be up to date" is enabled and main has moved ahead, auto-merge does not rebase on its own. You must rebase manually or enable "Automatically update branches" in Repo Settings.
Merge queue (advanced)
On large repos with an active main, auto-merge alone is not
enough: while you wait for CI, another PR lands in main and your
CI result is stale. GitHub Merge Queue solves this. PRs line up in
a queue; GitHub builds a temporary branch
gh-readonly-queue/... (event merge_group), appends PR commits
on top of the latest main in queue order, runs CI on that branch,
and fast-forwards main on success. Each PR is tested in the exact
state it will actually land, so conflicts and regressions caused
by combinations of PRs are caught before merge.