Branches & Commits¶
Branch management, commit listing/inspection, file blame, and CI commit-status manipulation.
Feature toggle
Opt-in. Enable via GITLAB_TOOLSETS=branches (or GITLAB_TOOLSETS=all), list individual tools in GITLAB_TOOLS=, or activate at runtime with the discover_tools MCP tool. 6 of these tools (get_branch, list_branches, list_commits, get_commit, get_commit_diff, get_file_blame) are already enabled by default via core; the toggle applies to the rest.
Tools in this group¶
create_branch— ✏️ Writesget_branch— 📖 Read-onlylist_branches— 📖 Read-onlydelete_branch— ✏️ Writeslist_protected_branches— 📖 Read-onlyget_protected_branch— 📖 Read-onlyprotect_branch— ✏️ Writesupdate_protected_branch— ✏️ Writesunprotect_branch— ✏️ Writesupdate_default_branch— ✏️ Writeslist_commits— 📖 Read-onlyget_commit— 📖 Read-onlyget_commit_diff— 📖 Read-onlyget_file_blame— 📖 Read-onlylist_commit_statuses— 📖 Read-onlycreate_commit_status— ✏️ Writes
create_branch¶
✏️ Writes
Create a new branch. Create a branch from a source branch, tag, or commit. Use protect_branch after creation. Returns already-exists when the name is taken.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch |
string | ✓ | Name for the new branch |
ref |
string | Source branch/commit for new branch |
get_branch¶
📖 Read-only
Get branch details (commit, protection status). To find resources, use the matching list or search tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch_name |
string | ✓ | Name of the branch |
list_branches¶
📖 Read-only
List branches in project with search filter. For one known resource, use the matching get tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
search |
string | Search term to filter branches by name | |
page |
number | Page number for pagination (default: 1) | |
per_page |
number | Number of items per page (max: 100, default: 20) |
delete_branch¶
✏️ Writes
Delete branch from project. Permanently delete a remote branch. Confirm the name first with get_branch or list_branches; this does not remove branch protection.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch_name |
string | ✓ | Name of the branch to delete |
list_protected_branches¶
📖 Read-only
List protected branches in a project, supports search filter. For one known resource, use the matching get tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
search |
string | Search term to filter protected branches by name | |
page |
number | Page number for pagination (default: 1) | |
per_page |
number | Number of items per page (max: 100, default: 20) |
get_protected_branch¶
📖 Read-only
Get details of a single protected branch (access levels, force push settings). To find resources, use the matching list or search tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch_name |
string | ✓ | Name of the protected branch |
protect_branch¶
✏️ Writes
Protect a repository branch (set push/merge/unprotect access levels). Create a protection rule; GitLab returns 409 if one exists. Use update_protected_branch to change an existing rule.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch_name |
string | ✓ | Branch name or wildcard pattern to protect |
name |
string | Deprecated alias for branch_name; prefer branch_name for consistency | |
push_access_level |
integer | Access level for pushing (0=No access, 30=Developer, 40=Maintainer, 60=Admin). GitLab default applies when omitted. | |
merge_access_level |
integer | Access level for merging (0=No access, 30=Developer, 40=Maintainer, 60=Admin). GitLab default applies when omitted. | |
unprotect_access_level |
integer | Access level for unprotecting (0=No access, 30=Developer, 40=Maintainer, 60=Admin). GitLab default applies when omitted. | |
allow_force_push |
boolean | Allow force push to the protected branch. Default: false | |
code_owner_approval_required |
boolean | Require code owner approval before merging (PREMIUM). Default: false |
update_protected_branch¶
✏️ Writes
Update an existing protected branch rule in place (access levels, force push, code owner approval). Change an existing protection rule in place (do not unprotect first). Read record ids with get_protected_branch. In allowed_to_push, allowed_to_merge, and allowed_to_unprotect, add with access_level, user_id, group_id, or deploy_key_id (push only); change with id; remove with {id, _destroy: true}. member_role_id is not supported. A request that would leave allowed_to_unprotect empty is refused. GitLab may reject the update unless the caller is on the current unprotect list.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch_name |
string | ✓ | Name or wildcard pattern of the existing protected branch |
allow_force_push |
boolean | Allow users who can push to the branch to force push | |
code_owner_approval_required |
boolean | Require code owner approval before merging. GitLab documents this as Premium/Ultimate | |
allowed_to_push |
array | Push access entries to add, change, or remove. GitLab documents access_level, user_id, and group_id entries as Premium/Ultimate, and deploy_key_id entries as Free from 18.10 | |
allowed_to_merge |
array | Merge access entries to add, change, or remove. GitLab documents access_level, user_id, and group_id entries as Premium/Ultimate | |
allowed_to_unprotect |
array | Unprotect access entries to add, change, or remove; 0 is not allowed. GitLab documents access_level, user_id, and group_id entries as Premium/Ultimate |
unprotect_branch¶
✏️ Writes
Remove protection from a previously protected branch. Remove protection. Use update_protected_branch to change access levels without removing the rule.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
branch_name |
string | ✓ | Name of the protected branch to unprotect |
update_default_branch¶
✏️ Writes
Change the default branch of a project. Change the project's default branch. Use create_branch to create a branch rather than changing defaults.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
default_branch |
string | ✓ | The new default branch name for the project |
list_commits¶
📖 Read-only
List repository commits with filtering options. For one known resource, use the matching get tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
ref_name |
string | The name of a repository branch, tag or revision range, or if not given the default branch | |
since |
string | Only commits after or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | |
until |
string | Only commits before or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | |
path |
string | The file path | |
author |
string | Search commits by commit author | |
all |
boolean | Retrieve every commit from the repository | |
with_stats |
boolean | Stats about each commit are added to the response | |
first_parent |
boolean | Follow only the first parent commit upon seeing a merge commit | |
order |
enum (default | topo) |
List commits in order | |
trailers |
boolean | Parse and include Git trailers for every commit | |
page |
number | Page number for pagination (default: 1) | |
per_page |
number | Number of items per page (max: 100, default: 20) |
get_commit¶
📖 Read-only
Get details of a specific commit. To find resources, use the matching list or search tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
sha |
string | ✓ | The commit hash or name of a repository branch or tag |
stats |
boolean | Include commit stats |
get_commit_diff¶
📖 Read-only
Get changes/diffs of a specific commit. Return the file diffs for one commit. Use get_commit for metadata without the patch.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
sha |
string | ✓ | The commit hash or name of a repository branch or tag |
full_diff |
boolean | Whether to return the full diff or only first page (default: false) |
get_file_blame¶
📖 Read-only
Get git blame for a file at a given ref. Each entry maps a contiguous range of source lines to the commit that last changed them (id, author, authored_date, message). Use range_start/range_end to limit blame to specific lines.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
file_path |
string | ✓ | The full path of the file to blame, relative to repo root |
ref |
string | ✓ | The name of branch, tag or commit (required by GitLab blame API) |
range_start |
integer | First line of the blame range (inclusive, 1-based). Both range[start] and range[end] must be set together. | |
range_end |
integer | Last line of the blame range (inclusive, 1-based). Both range[start] and range[end] must be set together. |
list_commit_statuses¶
📖 Read-only
List statuses for a commit.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
sha |
string | ✓ | The commit hash or name of a repository branch or tag |
ref |
string | Filter statuses by Git ref | |
stage |
string | Filter statuses by build stage | |
name |
string | Filter statuses by status name or context | |
pipeline_id |
number | Filter statuses by pipeline ID | |
order_by |
enum (id | pipeline_id) |
Field to order statuses by | |
sort |
enum (asc | desc) |
Sort direction | |
all |
boolean | Return all statuses, not only latest ones | |
page |
number | Page number for pagination (default: 1) | |
per_page |
number | Number of items per page (max: 100, default: 20) |
create_commit_status¶
✏️ Writes
Create or update the status of a commit.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | ✓ | Project ID or complete URL-encoded path to project |
sha |
string | ✓ | The commit hash to set the status on |
state |
enum (pending | running | success | failed | canceled | skipped) |
✓ | Commit status state |
ref |
string | The branch or tag ref | |
name |
string | Status name. GitLab defaults to 'default' when omitted. | |
context |
string | Alias for name. Provide either name or context, not both. | |
target_url |
string | Target URL associated with this status | |
description |
string | Short status description | |
coverage |
number | Total code coverage for this status | |
pipeline_id |
number | Pipeline ID to attach the status to |