Problem
merge_pull_request currently has no way for a caller to atomically assert
which pull-request HEAD is being merged.
An agent can inspect a pull request, validate CI/review readiness, and then
call merge_pull_request, but the PR HEAD may change between those steps.
Without a compare-and-swap condition on the merge call, that creates a TOCTOU
gap.
The GitHub REST merge endpoint already supports the optional sha field for
this purpose, and go-github already exposes it as
PullRequestOptions.SHA. The MCP tool currently does not expose or forward
that capability.
Proposed change
Add an optional expectedHeadSha input to merge_pull_request and pass it
directly to github.PullRequestOptions.SHA.
This follows the existing expectedHeadSha naming used by
update_pull_request_branch.
When supplied:
- the exact expected HEAD SHA is sent to GitHub as the REST
sha field;
- a changed HEAD is rejected by GitHub rather than merging a different commit;
- no retry or permissive fallback is introduced.
When omitted, behavior remains backward compatible because the underlying
sha field is optional/omitted.
Scope
No authentication, credential, logging, permission, or unrelated tool changes.
Problem
merge_pull_requestcurrently has no way for a caller to atomically assertwhich pull-request HEAD is being merged.
An agent can inspect a pull request, validate CI/review readiness, and then
call
merge_pull_request, but the PR HEAD may change between those steps.Without a compare-and-swap condition on the merge call, that creates a TOCTOU
gap.
The GitHub REST merge endpoint already supports the optional
shafield forthis purpose, and
go-githubalready exposes it asPullRequestOptions.SHA. The MCP tool currently does not expose or forwardthat capability.
Proposed change
Add an optional
expectedHeadShainput tomerge_pull_requestand pass itdirectly to
github.PullRequestOptions.SHA.This follows the existing
expectedHeadShanaming used byupdate_pull_request_branch.When supplied:
shafield;When omitted, behavior remains backward compatible because the underlying
shafield is optional/omitted.Scope
No authentication, credential, logging, permission, or unrelated tool changes.