Sitelet https://github.com/github/github-mcp-server/pull/3868
Skip to content

feat(pull_requests): add merge queue tools - #3868

Open
Mystery01092000 wants to merge 1 commit into
github:mainfrom
Mystery01092000:feat/merge-queue-tools
Open

Mystery01092000 wants to merge 1 commit into
github:mainfrom
Mystery01092000:feat/merge-queue-tools

Conversation

@Mystery01092000

Copy link
Copy Markdown

Summary

Adds merge queue support to the pull_requests toolset: two new tools, enqueue_pull_request and dequeue_pull_request, plus a get_merge_queue_status method on pull_request_read.

Why

On a base branch that requires a merge queue, GitHub rejects the REST merge that merge_pull_request uses. Until now an MCP client had to fall back to gh pr merge --auto or raw GraphQL to land the pull request. This follows the proposal in the issue, and keeps merge queues separate from auto-merge (#2411).

Fixes #3669

What changed

  • enqueue_pull_request (write) wraps enqueuePullRequest. It takes owner, repo and pullNumber, plus optional jump (front of the queue) and expectedHeadSha (sent as expectedHeadOid, mirroring merge_pull_request). It returns the merge queue entry: id, position, state, enqueued_at, estimated_time_to_merge, jump and solo. jump: false is not sent.
  • dequeue_pull_request (write) wraps dequeuePullRequest and returns the removed entry, or null when GitHub returns none.
  • pull_request_read get_merge_queue_status reads isMergeQueueEnabled, isInMergeQueue and mergeQueueEntry. It returns {"merge_queue_enabled": bool, "in_merge_queue": bool, "entry": {...}}, with entry omitted when the pull request isn't queued.
    • The issue suggested returning null when there is no merge queue. I went with an explicit object instead: merge_queue_enabled: false tells a client to use merge_pull_request, while merge_queue_enabled: true, in_merge_queue: false tells it to enqueue. A bare null can't tell those two apart. Happy to change it if you prefer the other shape.
  • The write tools look up the pull request's node ID with the existing resolvePullRequestNodeID.
  • Typed outputs follow the existing consolidated pull request conventions: a new variant in pullRequestReadOutputSchema, a nullable entry schema for the write tools, and shape-aware field descriptions, including the state enum QUEUED | AWAITING_CHECKS | MERGEABLE | UNMERGEABLE | LOCKED.
  • The pull-request-authoring skill maps both tools as optional. Its decision points now say when to enqueue instead of merging, and that the same confirmation applies.
  • The tools are registered in tools.go, with toolsnaps and README regenerated.

Not included: the issue's nice-to-have of a clearer merge_pull_request error pointing to enqueue_pull_request. It can be a follow-up.

MCP impact

  • No tool or API changes
  • Tool schema or behavior changed: pull_request_read gains the get_merge_queue_status method. The other methods are unchanged.
  • New tool added: enqueue_pull_request and dequeue_pull_request.

Prompts tested (tool changes only)

  • "Is microsoft/vscode PR #348609 in the merge queue? What position is it in?" I ran this against live GitHub through the locally built server over stdio. It returned {"merge_queue_enabled":true,"in_merge_queue":true,"entry":{"id":"MQE_…","position":1,"state":"AWAITING_CHECKS","enqueued_at":"2026-11-16T19:10:10Z","estimated_time_to_merge":832,"jump":false,"solo":false}}.
  • "Does github/github-mcp-server use a merge queue for PR feat: Support choosing the merge commit author email #3852?" This returned {"merge_queue_enabled":false,"in_merge_queue":false}.
  • "Add PR [docker] build arm64 #42 to the merge queue at the front", and "Remove PR [docker] build arm64 #42 from the merge queue, I need to push a fix first." These are covered by mocked GraphQL tests (exact mutation inputs and response mapping). I couldn't run the mutations live: merge queues are only available on organization-owned repositories, and I didn't want to enqueue pull requests in a repository I don't own.

Security / limits

  • No security or limits impact
  • Auth / permissions considered: both write tools require repo, like merge_pull_request. The status method uses the same PublicRead(repo) scope and IFC labelling as the other pull_request_read methods.
  • Data exposure, filtering, or token/size limits considered

Tool renaming

  • I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
    • I have added the new tool aliases in deprecated_tool_aliases.go
  • I am not renaming tools as part of this PR

Lint & tests

  • Linted locally with ./script/lint: golangci-lint v2.14.0 reports 0 issues, and gofmt -s -l . is clean.
  • Tested locally with ./script/test: go test ./... passes with Go 1.27.4. New tests are in pullrequests_merge_queue_test.go (mutation inputs, including jump/expectedHeadOid, GraphQL error paths, a missing pull request, output schemas, the timestamp conversion), plus typed end-to-end cases in typed_consolidated_pull_request_outputs_test.go.

Docs

  • Not needed
  • Updated (README / docs / examples): regenerated with script/generate-docs.

Skills

  • Updated relevant skills or confirmed no bundled skill applies: pull-request-authoring (tool mapping and a merge-queue decision point).

Repositories that require a merge queue reject merge_pull_request, so MCP
clients had to fall back to the gh CLI or raw GraphQL to land a pull
request there.

- enqueue_pull_request wraps the enqueuePullRequest mutation, with the
  optional jump flag and expectedHeadSha (expectedHeadOid).
- dequeue_pull_request wraps dequeuePullRequest.
- pull_request_read gains a get_merge_queue_status method. It reports
  whether the base branch requires a merge queue and, if the pull request
  is queued, its position, state, enqueue time, estimated time to merge
  and jump/solo flags.

Both write tools return the merge queue entry. The pull-request-authoring
skill now maps both tools and says when to enqueue instead of merging.

Fixes github#3669
@Mystery01092000
Mystery01092000 requested a review from a team as a code owner November 16, 2026 19:25
Copilot AI adaptive review requested due to automatic review settings November 16, 2026 19:25

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The new GraphQL queue mutations can trigger automatic merges and reorder work, introducing interactions with branch rules, merge authorization, and dequeue semantics beyond limited-consequence review scope.

No open issues 🎉

What changed in this PR

Adds merge queue support to the GitHub MCP Server’s pull_requests toolset, allowing clients to manage queue-based merges without falling back to the CLI or raw GraphQL. This addresses #3669 while keeping merge queues separate from auto-merge.

Changes:

  • Adds enqueue and dequeue tools, including optional queue priority and expected-head protection.
  • Extends pull_request_read with queue status and typed output schemas.
  • Adds regression coverage, schema snapshots, generated documentation, and skill guidance.
File Description
README.md Documents queue tools and the new read method.
pkg/​skills/​catalog/​tools.go Maps queue tools to the authoring skill.
pkg/​skills/​catalog/​skills/​pull-request-authoring/​SKILL.md Explains queue selection and confirmation requirements.
pkg/​github/​typed_consolidated_pull_request_outputs_test.go Covers queue outputs through MCP sessions.
pkg/​github/​tools.go Registers enqueue and dequeue tools.
pkg/​github/​pullrequests.go Routes the queue-status read method.
pkg/​github/​pullrequests_merge_queue.go Implements GraphQL queue operations and response types.
pkg/​github/​pullrequests_merge_queue_test.go Tests inputs, errors, status responses, and schemas.
pkg/​github/​consolidated_pull_request_types.go Adds queue output schemas and argument normalization.
pkg/​github/​__toolsnaps__/​pull_request_read.snap Captures the expanded read schema.
pkg/​github/​__toolsnaps__/​enqueue_pull_request.snap Records the enqueue tool schema.
pkg/​github/​__toolsnaps__/​dequeue_pull_request.snap Records the dequeue tool schema.

Review effort: Balanced (adaptive)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add merge queue support to pull request tools (enqueue, dequeue, queue status)

2 participants