Merge a GitHub Pull Request Safely with gh pr merge

Clicking the green button is fine until you are merging the same pull request shape fifty times a week, and that is when gh pr merge earns its place. The examples target GitHub CLI 2.87.3, installed here from the gh package. GitHub's rules, required checks and merge queue still decide whether the operation can complete.

Allow about ten minutes for a straightforward merge, plus however long the repository's checks take. You need an authenticated gh installation, permission to merge the pull request, a repository name or a checked-out branch, and enough context to decide whether merge, rebase or squash is appropriate. No example needs sudo. Merging changes remote state, so read the pull request and its checks before running the final command.

1. Confirm the installed command

Start with read-only checks. They confirm the executable and the option set without contacting a repository or changing anything:

$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh pr merge --help

The local manual describes the command as gh pr merge [<number> | <url> | <branch>] [flags]. The argument can be a pull request number, its URL, or a branch. Omit it and gh selects the pull request belonging to the current branch, which is only a convenience once you have checked what that branch actually is.

2. Identify the pull request and repository

Use a full pull request URL when you are working across several repositories. This makes the target visible in shell history:

$ gh pr merge https://github.com/OWNER/REPOSITORY/pull/123 --squash

Replace every uppercase placeholder, and confirm the number and repository in the URL before pressing Enter. You can select a different repository explicitly with the inherited --repo option:

$ gh pr merge 123 --repo OWNER/REPOSITORY --squash

For a pull request in the repository associated with your current branch, check the branch name before relying on the no-argument form:

$ git branch --show-current
feature/example-change
$ gh pr merge --help

A local branch name is not guaranteed unique across repositories. If there is any doubt, use the URL or --repo form. If authentication or permission fails, fix that separately: do not work around an access error with administrator privileges.

3. Choose the merge method

Pass exactly the strategy agreed for the repository. The installed command provides three strategy flags:

• --merge merges the commits into the base branch.
• --rebase rebases the commits onto the base branch.
• --squash combines the pull request's commits into one commit and merges it into the base branch.

Squashing is a common choice when the pull request contains noisy fix-up commits, but the repository's history policy decides. If the repository uses a merge queue, the command behaves differently: no strategy is required. With required checks still pending, auto-merge is enabled; once those checks pass, the pull request joins the queue.

For a normal, already-approved pull request where the project wants one commit, a deliberately explicit invocation looks like this:

$ gh pr merge 123 --repo OWNER/REPOSITORY --squash \
    --subject "Add example change" \
    --body "Explain the user-visible result and verification."

--subject and --body provide the merge commit text. Use --body-file FILE when the explanation is longer, or --body-file - to read it from standard input. Keep shell quoting around subjects and paths so punctuation is not interpreted by the shell.

4. Decide whether to wait for checks

--auto tells gh to merge automatically only after necessary requirements are met. Use it when the request is "merge when the required checks and approvals pass", rather than "merge immediately if possible":

$ gh pr merge 123 --repo OWNER/REPOSITORY --squash --auto

This may leave the pull request open while GitHub waits, and that is expected. The command's output and the pull request page are the authoritative status: do not assume a successful invocation means a merge commit already exists when auto-merge or a merge queue is involved.

If auto-merge has been enabled for the pull request and you need to turn that setting off, use the separate option:

$ gh pr merge 123 --repo OWNER/REPOSITORY --disable-auto

This changes the pull request's merge setting, so use it only when you are authorised to cancel the pending automatic merge. If a queue is enabled by repository policy, disabling auto-merge does not give you a way around that policy.

5. Protect against merging the wrong revision

Pull request heads can change after review. --match-head-commit SHA adds a guard: the pull request head must still have the specified commit SHA for the merge to be allowed:

$ gh pr merge 123 --repo OWNER/REPOSITORY --squash \
    --match-head-commit abcdef0123456789abcdef0123456789abcdef01

Replace the example SHA with the exact reviewed head commit from your trusted review or status output. If the head changed, treat a refusal as useful protection: recheck the diff and checks, then rerun with the newly approved SHA. Do not remove the guard merely to make the command succeed.

The --author-email option changes the email recorded for a merge commit. Use it only when the repository's contribution or identity policy explicitly requires it. It does not change who is authorised to merge.

6. Understand the dangerous options

--delete-branch deletes the local and remote branch after the merge. This is convenient, but it changes two locations and can remove a branch another tool or person still expects. Leave it out until you have confirmed the branch is disposable:

$ gh pr merge 123 --repo OWNER/REPOSITORY --squash --delete-branch

--admin uses administrator privileges to merge a pull request that does not meet requirements. It can bypass protections and, according to the local manual, bypass a merge queue when used to merge directly. Treat it as an emergency exception with an explicit reason and audit trail, not a fix for failing tests, missing approval or a wrong target.

7. Verify the result

Read the command's final output and check the pull request in GitHub. A practical shell checkpoint is to ask for help again, which confirms the command remains available, then inspect your local repository without changing it:

$ gh pr merge --help >/dev/null && echo "gh pr merge is available"
gh pr merge is available
$ git status --short