With the GitHub CLI, how do `gh pr merge --auto` and `gh pr merge --admin` differ when a pull request's required checks are still running?
answer
- wait for the rules or override them
- mutually exclusive flags
- blocked, behind, conflicting
- pin the commit you reviewed
basics
~20 s--auto turns on auto-merge, so GitHub merges once requirements such as the checks are met and gh returns at once; --admin merges now with administrator privileges, past a blocked or out-of-date state, but never past merge conflicts.
solid answer
~40 sIn a script, `gh pr merge` needs one of `--merge`, `--squash` or `--rebase`, unless the base branch uses a merge queue. Without either flag, a pull request that is blocked or behind its base makes gh print the reason, suggest `--auto`, and exit non-zero. `--auto` enables auto-merge with the chosen method and returns immediately, though a pull request that is already mergeable is merged on the spot. `--admin` uses administrator privileges to merge despite a blocked or behind state and bypasses a merge queue; a conflicting pull request still needs the conflict resolved, and GitHub still checks that your account may bypass. The three flags `--auto`, `--disable-auto` and `--admin` are mutually exclusive. `--match-head-commit <sha>` makes the merge fail if new commits arrived after your review.
code
bash · 6 lines# Hand it to GitHub: merge by squash once requirements are met
gh pr merge 482 --squash --auto
# Or wait here, then merge exactly the commit that was reviewed
gh pr checks 482 --watch --fail-fast --required \
&& gh pr merge 482 --squash --delete-branch --match-head-commit "$REVIEWED_SHA"go deeper
Recall that gh pr merge needs a method flag in scripts, and that --auto means merge once the requirements are met.
Explain the merge states gh reacts to: clean, blocked, behind and conflicting, and what --auto does in each, including the immediate merge when nothing blocks.
Show when --admin is justified, why it cannot get past conflicts, how merge queues change the flags, and why --match-head-commit belongs in careful merges.
Weigh who should hold bypass rights at all, and how a team keeps terminal merges from becoming the quiet path around the review and check policy.
## The scenario You have reviewed a colleague's pull request, its required checks are still running, and you want it landed without babysitting a browser tab. `gh pr merge` has three ways to finish the job: wait, hand the job to GitHub, or override the rules. Knowing which one each flag means, and what it bypasses, is the senior part of the question. ## The baseline: what plain gh pr merge does gh reads the pull request's **merge state** from GitHub before acting: - **Clean**, or mergeable with only non-required checks failing: it merges. - **Blocked**, meaning the base branch's policy prohibits the merge (required checks pending or failing, a missing approval and so on): it prints that the pull request is not mergeable, suggests `--auto`, mentions `--admin`, and exits non-zero. - **Behind**, meaning the head is not up to date with the base and the base branch requires it: same as blocked. - **Dirty**, meaning the merge commit cannot be cleanly created: gh reports it, and when it finds your remote for the base repository it prints a `gh pr checkout <n> && git fetch ... && git merge ...` recipe to resolve the conflicts locally, then exits non-zero. Two more rules apply in scripts. Without a terminal, gh requires exactly one of `--merge`, `--squash` or `--rebase`, and two of them together are an error. The interactive prompt offers only the methods the repository allows. ## --auto against --admin | | `--auto` | `--admin` | |---|---|---| | What it asks for | enable auto-merge; GitHub merges once the necessary requirements are met | merge now using administrator privileges | | Pending required checks | waits for them, on GitHub's side | merges without them | | Head behind base | waits until requirements are met | merges anyway | | Merge conflicts | cannot merge until they are resolved | still fails; conflicts are never bypassed | | Merge queue on the base | n/a (see below) | bypasses the queue and merges directly | | Branch deletion by gh | none; gh exits before the merge happens | as requested with `--delete-branch` | | Who can use it | anyone who may merge, if auto-merge is allowed on the repository | only accounts GitHub lets bypass the rules | Details: 1. `--auto` does not block your terminal. gh enables auto-merge with your chosen method, prints that the pull request will be merged via squash (or rebase, or merge) when all requirements are met, and exits 0. `--disable-auto` turns it off again. 2. If the pull request is **already** mergeable when you pass `--auto`, gh merges it immediately instead of enabling auto-merge. `--auto` means "merge as soon as allowed", which can be now. 3. Because the auto-merge case returns before anything is merged, gh skips its own local and remote branch deletion. Whether the head branch is removed after the eventual merge depends on the repository's setting for deleting head branches. 4. `--admin` is not a permission in itself. gh sends the merge, and GitHub decides whether your account may bypass. If you are not allowed, the merge is refused. 5. `--auto`, `--disable-auto` and `--admin` are mutually exclusive. ## Merge queues change the defaults When the base branch requires a **merge queue**, gh's help spells out different behaviour: - No merge method is required, and a method you pass only triggers a warning that the queue sets it. - If required checks have not yet passed, auto-merge is enabled. If they have, the pull request is added to the queue. - `--delete-branch` is rejected, because deleting the branch could close the pull request and pull it out of the queue. - `--admin` bypasses the queue and merges directly. How a queue builds and tests merge groups is GitHub behaviour, covered with merge queues. ## Guarding the commit you actually reviewed Between your review and the merge, the author, or anyone else with push access, can push another commit. `--match-head-commit <sha>` passes the SHA you reviewed, and the merge goes through only if the pull request's head still matches it. When you merge from the pull request's own branch without giving a number, gh also warns if the pull request has diverged from your local branch, but that is a warning, not a guard. ## Waiting in the terminal instead If you would rather watch than delegate, `gh pr checks 482 --watch` polls every 10 seconds (`--interval`). `--fail-fast` stops at the first failure, and `--required` limits it to required checks. It exits 1 if any check failed. Without `--watch`, it exits 8 while checks are pending, which scripts can test for. Chaining `gh pr checks 482 --watch --fail-fast && gh pr merge 482 --squash --delete-branch` merges only after a green run, and still lets branch protection have the final word. ## The judgement interviewers look for `--admin` is the flag that turns "the checks are slow" into "the checks were skipped". It belongs in incidents with a written reason, not in muscle memory. Which roles may bypass, and how bypasses are audited, is decided in branch protection and rulesets, not in gh. A senior answer chooses `--auto` (or `checks --watch` followed by a merge) by default, pins `--match-head-commit` when the review must match the merge, and treats `--admin` as an exception someone can explain afterwards.
- You run `gh pr merge 482 --squash --auto --delete-branch` and the branch is still there after the merge. Why?With `--auto`, gh only enables auto-merge and exits before anything merges, so it skips its own local and remote branch deletion. Removing the head branch afterwards is up to the repository's setting for deleting head branches, or a later cleanup.
- Why might `gh pr merge 482 --admin` still fail for a repository admin?The pull request may have merge conflicts, which no flag bypasses, so you resolve them first, for example after `gh pr checkout 482`. Or the rules on the base branch may not let your role bypass them. gh sends the merge, and GitHub decides whether the bypass is allowed.
- gh pr merge --auto keeps the terminal waiting until the merge happens
- --admin lets you merge a pull request that has merge conflicts
- --auto always defers the merge, even when the pull request is already mergeable
- Passing --admin grants admin rights to whoever runs the command
- --delete-branch works the same whether or not a merge queue is required