Skip to content

Add atomic head SHA pinning to merge_pull_request #3181

Description

@jcosta1970

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions