Branch & Commit Operations
Relevant source files
The following files were used as context for generating this wiki page:
The Branch & Commit Operations module provides the core functionality for interacting with the version control aspects of GitHub repositories through the Model Context Protocol (MCP). This system allows for the programmatic management of repository structures, enabling users to create branches, retrieve commit histories, and execute complex file changes across multiple documents in a single atomic operation.
These operations leverage the GitHub Git Data API and Repositories API to perform both high-level actions (like branch listing) and low-level Git plumbing tasks (like tree and commit object creation). The module is designed to support agentic workflows by providing "minimal" data structures that reduce token consumption while maintaining the essential context required for development tasks.
Sources: pkg/github/repositories.go, pkg/github/minimal_types.go, cmd/github-mcp-server/generate_docs.go
Branch Management
Branch management encompasses tools for discovering, creating, and resolving references within a repository. The system supports both simple branch listing and complex reference resolution that can handle short names, fully qualified refs, or specific commit SHAs.
Reference Resolution Logic
A critical component of the branch system is the resolveGitReference function. This logic ensures that various input formats (branch names, tags, or SHAs) are correctly mapped to definitive Git objects.
The resolution logic follows a strict priority: explicit SHAs take precedence, followed by fully qualified references, and finally a fallback search through branches then tags.
Sources: pkg/github/repositories.go:1022-1087
Branch Tools
The system exposes several tools for branch interaction:
| Tool | Purpose | Key Parameters |
|---|---|---|
list_branches | Retrieves all branches in a repository | owner, repo, page, perPage |
create_branch | Creates a new branch from a source | owner, repo, branch, from_branch |
Sources: pkg/github/repositories.go:174-210, pkg/github/repositories.go:580-621
Commit Operations
Commit operations provide the ability to inspect history and create new state changes. The module implements specialized tools like push_files to allow multiple changes in one commit, which is more efficient for LLM-driven development than individual file updates.
Atomic Multi-File Commits
The push_files tool implements a sequence of Git Data API calls to ensure that multiple files are committed together. This involves fetching the base commit, creating a new Git tree, and then creating a new commit object.
This sequence ensures that even if one file fails to validate, the entire commit operation is aborted, maintaining repository integrity.
Sources: pkg/github/repositories.go:656-745, pkg/github/repositories_test.go:816-880
Commit Inspection
Tools for inspecting commits include:
- get_commit: Retrieves full details of a specific commit, including optional diffs and statistics.
- list_commits: Provides a paginated history of commits on a specific branch or path.
Sources: pkg/github/repositories.go:27-77, pkg/github/repositories.go:94-142
Data Structures
To optimize performance and reduce payload size, the module uses "minimal" types. These structures extract only the most relevant fields from the verbose GitHub API responses.
Minimal Commit Schema
The convertToMinimalCommit function handles the transformation from github.RepositoryCommit to MinimalCommit, optionally omitting diff information based on the includeDiffs flag.
Sources: pkg/github/minimal_types.go:64-150
Implementation Details
File Deletion Architecture
Interestingly, the delete_file tool does not use the standard REST file deletion endpoint. Instead, it uses a custom implementation via the Git Data API. This is done to ensure automatic commit signing when the MCP server is acting as a GitHub App or GitHub Actions user, a feature that the standard REST deletion endpoint occasionally lacks.
The process involves:
- Fetching the current branch head.
- Creating a new Git Tree where the target file's SHA is set to
nil. - Committing that tree and updating the branch reference.
Sources: pkg/github/repositories.go:487-578, pkg/github/repositories_test.go:1078-1115
Pagination Configuration
Most list operations support standard pagination parameters through the WithPagination helper.
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | The page number to retrieve |
perPage | integer | 30 | Results per page (max 100) |
Sources: pkg/github/repositories.go:142, cmd/github-mcp-server/generate_docs.go:250-255
Summary
The Branch & Commit Operations system serves as the foundational interface for modifying and inspecting the version history of a repository. By combining high-level repository tools with low-level Git plumbing, it provides a robust platform for agents to perform complex coding tasks, such as multi-file refactoring and branch-based feature development, while maintaining repository integrity and security via signed commits.