gh pr merge: Usage, Options & Common CI Errors
Merge a pull request - squash, rebase, or merge commit - from the CLI.
gh pr merge merges a pull request using the strategy you pick and can optionally enable auto-merge so the PR lands once checks pass.
What it does
gh pr merge merges a PR via merge commit (--merge), squash (--squash), or rebase (--rebase). --auto enables auto-merge (merges automatically when required checks and reviews pass), and --delete-branch removes the head branch afterward. In CI you must specify the strategy so it does not prompt.
Common usage
# Squash-merge and delete the branch (non-interactive)
gh pr merge 42 --squash --delete-branch
# Enable auto-merge so it lands when checks pass
gh pr merge 42 --auto --squash
# Rebase-merge a specific PR
gh pr merge 42 --rebaseCommon error in CI: prompts for method / not mergeable
gh pr merge hangs asking "What merge method would you like to use?" in a non-TTY, or fails with "Pull request is not mergeable" (conflicts, failing required checks, or a disabled merge method). Fix: always pass one of --merge/--squash/--rebase in CI; for not-mergeable, use --auto so it queues until checks pass, resolve conflicts, and confirm the chosen strategy is enabled in the repo’s branch protection. GH_TOKEN needs repo scope and contents: write / pull-requests: write.
Key options
| Option | Purpose |
|---|---|
| --merge / --squash / --rebase | Merge strategy (required in CI) |
| --auto | Merge automatically when checks pass |
| -d, --delete-branch | Delete the head branch after merge |
| --admin | Use admin privileges to override |
Using this in CI
Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.
- Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange
id-token: writefor cloud credentials with no stored secret. - Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
- Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
- Set the output format explicitly (
--output json) rather than relying on the default, which can differ by version and configuration profile.