Pull Request Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Pull Request Management within the GitHub MCP Server project encompasses a comprehensive suite of tools designed to facilitate the lifecycle of code contributions. It provides Model Context Protocol (MCP) compliant interfaces to interact with GitHub's Pull Request (PR) features, including creation, retrieval, updates, and reviews. This module acts as a bridge between LLM-based agents and the GitHub API, allowing agents to perform complex engineering tasks like opening PRs, requesting reviews, and merging changes.
The system utilizes both GitHub REST API (v3) and GraphQL API (v4) to manage PR states, particularly for specialized operations like managing draft statuses or submitting multi-comment reviews. It is integrated into the broader Repository Management and issue tracking workflows.
Sources: pkg/github/pullrequests.go:1-30, cmd/github-mcp-server/generate_docs.go:160-170
Architecture and Tool Design
The Pull Request Management module is structured as a collection of "Tools" that follow the MCP specification. Each tool consists of a definition (name, description, and input schema) and a handler function that executes the actual API calls.
Core Tool Components
Each PR tool follows a consistent implementation pattern:
- Tool Definition: Defines the parameters (e.g.,
owner,repo,pullNumber) and provides a user-friendly title and description. - Handler Function: A
server.ToolHandlerFuncthat extracts arguments, authenticates via aGetClientFn, and performs the requested operation. - Translation Support: Uses a
TranslationHelperFuncto provide localized descriptions for tool metadata.
Sources: pkg/github/pullrequests.go:20-50, pkg/github/pullrequests.go:146-170
Technical Flow of a PR Tool Call
The following diagram illustrates the sequence of events when an MCP client (such as an LLM) invokes a Pull Request tool.
Pull Request Lifecycle Tools
The system supports the full lifecycle of a pull request, from initial creation to final merging.
Creation and Retrieval
The create_pull_request tool allows for the programmatic creation of PRs. It requires a head branch (source) and a base branch (target). The get_pull_request tool provides detailed metadata about a specific PR, including its state, URL, and associated branches.
| Tool Name | Operation | Key Parameters |
|---|---|---|
create_pull_request | POST /repos/{owner}/{repo}/pulls | title, head, base, draft, body |
get_pull_request | GET /repos/{owner}/{repo}/pulls/{number} | owner, repo, pullNumber |
list_pull_requests | GET /repos/{owner}/{repo}/pulls | state, sort, direction, pagination |
Sources: pkg/github/pullrequests.go:20-130, pkg/github/pullrequests.go:343-410
Branch and State Updates
Updating a PR can involve modifying its metadata (title, body) or its git state. The project provides specific tools for both REST-based metadata updates and GraphQL-based state changes (like draft status).
update_pull_request: A hybrid tool. It uses REST for title/body updates and GraphQL to toggle thedraftstatus ormarkPullRequestReadyForReview.update_pull_request_branch: Specifically used to merge the latest changes from the base branch into the head branch to resolve out-of-date PRs.
Sources: pkg/github/pullrequests.go:200-330, pkg/github/pullrequests.go:572-620
Review Management System
A significant portion of the PR management logic is dedicated to the review process. The system supports two modes: immediate submission and a staged "Pending Review" workflow.
Staged Review Workflow
To support complex reviews where an agent needs to add multiple comments across different files before notifying the author, the system implements a "Pending Review" state using the GraphQL API.
Automated and AI Reviews
The server includes specialized tools for automated review workflows:
request_copilot_review: Specifically requests a review from thecopilot-pull-request-reviewer[bot].create_and_submit_pull_request_review: An "atomic" tool for simple text-based reviews without line-specific comments.
Sources: pkg/github/pullrequests.go:1210-1250, pkg/github/pullrequests.go:740-780
Data Structures
The internal communication within the tools often uses a MinimalResponse structure to return essential identifiers without overloading the agent with the full API response.
type MinimalResponse struct {
ID string `json:"id"`
URL string `json:"url"`
}
Sources: pkg/github/pullrequests.go:138-141, pkg/github/pullrequests.go:321-324
Guided Workflows (Prompts)
The module provides high-level prompts that orchestrate multiple PR tools into a single developer workflow. One prominent example is the IssueToFixWorkflow.
Issue to Fix Workflow
This prompt guides the agent through:
- Creating a GitHub Issue.
- Assigning the issue to a coding agent (Copilot).
- Monitoring the resulting Pull Request creation.
Sources: pkg/github/workflow_prompts.go:12-65
Testing and Verification
The Pull Request management logic is heavily verified through two layers of testing:
- Mocked Unit Tests: Located in
pkg/github/pullrequests_test.go, these tests use mock HTTP clients and GraphQL matchers to verify tool definitions and handler logic across various API success and failure scenarios. - End-to-End (E2E) Tests: Located in
e2e/e2e_test.go, these tests run against real GitHub repositories (controlled by environment variables) to ensure the integrated tools work with the live GitHub API, including actual review submissions and deletions.
Sources: pkg/github/pullrequests_test.go:20-100, e2e/e2e_test.go:400-450
Summary
Pull Request Management in the GitHub MCP Server provides a robust interface for LLMs to act as autonomous contributors. By abstracting the complexities of GitHub's REST and GraphQL APIs into discrete, schema-validated tools, it enables automated code reviews, PR lifecycle management, and complex multi-step engineering workflows. Through the use of staged review tools and integrated workflows, the system ensures that AI-driven PR management remains accurate, professional, and consistent with human development practices.