gh pr merge
Merge a PR, your way
gh pr merge merges a pull request from the terminal and lets you choose the strategy — a merge commit, a squash, or a rebase. Add --auto to merge the moment checks pass, and --delete-branch to clean up afterward.
gh pr merge 123 --squash --delete-branchSyntax
gh pr merge [<number> | <url> | <branch>] [flags]Examples
Merge the current branch's PR interactively
gh pr mergeSquash and delete the branch
gh pr merge 123 --squash --delete-branchRebase merge
gh pr merge 123 --rebaseAuto-merge as soon as required checks pass
gh pr merge 123 --squash --autoSet the squash commit subject
gh pr merge 123 --squash --subject "Add caching layer"Options & flags
| Flag | What it does |
|---|---|
| -m, --merge | Create a merge commit. |
| -s, --squash | Squash all commits into one, then merge. |
| -r, --rebase | Rebase the commits onto the base branch. |
| --auto | Merge automatically once all requirements are met. |
| -d, --delete-branch | Delete the local and remote branch after merge. |
| --admin | Use admin privileges to merge past failing or pending checks. |
| -t, --subject | Commit subject for the merge or squash commit. |
| --body | Commit body text. |
How to use gh pr merge, step by step
- Confirm checks are green with
gh pr checks 123. - Choose a strategy flag:
--squash,--merge, or--rebase. - Run
gh pr merge 123 --squash --delete-branch. - For protected branches, add
--autoso gh merges once CI passes.
Common errors and fixes
Pull request is not mergeable: the base branch policy prohibits the merge
Required checks or reviews are not satisfied. Wait for CI, request the missing review, or if you have rights, merge with --admin.
GraphQL: Branch is not up to date with the base branch
Update the PR branch first: gh pr checkout 123 then rebase/merge base, push, and try again — or enable auto-merge with --auto.
--auto cannot be used: the repository does not allow auto-merge
Auto-merge must be enabled in the repository settings under Pull Requests before --auto works.
Related commands
Frequently asked questions
How do I squash and merge a PR with GitHub CLI?
Run gh pr merge <number> --squash. Add --delete-branch to remove the branch afterward and --subject to set the squash commit message.
What does gh pr merge --auto do?
--auto turns on GitHub's auto-merge: the PR merges by itself as soon as required status checks and reviews pass, so you don't have to wait and click. The repository must allow auto-merge.
Can I merge a PR that has failing checks?
Only with elevated rights. gh pr merge --admin bypasses branch protection if you are an administrator; otherwise you must wait for checks to pass.