branches

package
v2.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package branches implements MCP tools for GitLab branch and protected branch operations.

The package wraps the GitLab Branches and Protected branches APIs:

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ActionSpecs 

func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec

ActionSpecs returns canonical specs for branch and protected branch actions.

func Delete 

func Delete(ctx context.Context, client *gitlabclient.Client, input DeleteInput) error

Delete deletes a branch from a GitLab project.

func DeleteMerged 

func DeleteMerged(ctx context.Context, client *gitlabclient.Client, input DeleteMergedInput) error

DeleteMerged deletes all branches that have been merged into the default branch. The default branch and protected branches are never deleted.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a list of branches as a Markdown table.

func FormatOutputMarkdown 

func FormatOutputMarkdown(br Output) string

FormatOutputMarkdown renders a single branch as a Markdown summary.

func FormatProtectedListMarkdown 

func FormatProtectedListMarkdown(out ProtectedListOutput) string

FormatProtectedListMarkdown renders a list of protected branches as a Markdown table.

func FormatProtectedMarkdown 

func FormatProtectedMarkdown(pb ProtectedOutput) string

FormatProtectedMarkdown renders a single protected branch as Markdown.

Types

type BranchAccessDescriptionOutput added in v2.3.0 

type BranchAccessDescriptionOutput struct {
	ID                     int64  `json:"id"`
	AccessLevel            int    `json:"access_level"`
	AccessLevelDescription string `json:"access_level_description"`
	DeployKeyID            int64  `json:"deploy_key_id,omitempty"`
	UserID                 int64  `json:"user_id,omitempty"`
	GroupID                int64  `json:"group_id,omitempty"`
}

BranchAccessDescriptionOutput mirrors gl.BranchAccessDescription, an entry in a protected branch's push/merge/unprotect access-level arrays.

type BranchPermissionInput added in v2.3.0 

type BranchPermissionInput struct {
	ID          *int64 `json:"id,omitempty"           jsonschema:"ID of an existing access entry to update"`
	UserID      *int64 `json:"user_id,omitempty"      jsonschema:"Grant access to a specific user by ID"`
	GroupID     *int64 `json:"group_id,omitempty"     jsonschema:"Grant access to a specific group by ID"`
	DeployKeyID *int64 `json:"deploy_key_id,omitempty" jsonschema:"Grant access via a specific deploy key by ID"`
	AccessLevel *int   `json:"access_level,omitempty" jsonschema:"Coarse access level (0=No access, 30=Developer, 40=Maintainer)"`
	Destroy     *bool  `json:"_destroy,omitempty"     jsonschema:"When true, remove this existing access entry"`
}

BranchPermissionInput mirrors gl.BranchPermissionOptions, a single fine-grained allowed_to_{push,merge,unprotect} permission entry. Each entry grants access either by a coarse access level or by a specific user, group, or deploy key.

type CommitOutput added in v2.3.0 

type CommitOutput struct {
	ID               string              `json:"id"`
	ShortID          string              `json:"short_id"`
	Title            string              `json:"title"`
	Message          string              `json:"message,omitempty"`
	AuthorName       string              `json:"author_name"`
	AuthorEmail      string              `json:"author_email"`
	AuthoredDate     string              `json:"authored_date,omitempty"`
	CommitterName    string              `json:"committer_name"`
	CommitterEmail   string              `json:"committer_email"`
	CommittedDate    string              `json:"committed_date,omitempty"`
	CreatedAt        string              `json:"created_at,omitempty"`
	WebURL           string              `json:"web_url"`
	ParentIDs        []string            `json:"parent_ids,omitempty"`
	Status           string              `json:"status,omitempty"`
	ProjectID        int64               `json:"project_id,omitempty"`
	Trailers         map[string]string   `json:"trailers,omitempty"`
	ExtendedTrailers map[string]string   `json:"extended_trailers,omitempty"`
	LastPipeline     *LastPipelineOutput `json:"last_pipeline,omitempty"`
	Stats            *CommitStatsOutput  `json:"stats,omitempty"`
}

CommitOutput mirrors gl.Commit, the full commit object embedded on a branch payload as commit.

type CommitStatsOutput added in v2.3.0 

type CommitStatsOutput struct {
	Additions int64 `json:"additions"`
	Deletions int64 `json:"deletions"`
	Total     int64 `json:"total"`
}

CommitStatsOutput mirrors gl.CommitStats: line additions/deletions/total for a commit.

type CreateInput 

type CreateInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"  jsonschema:"Project ID or URL-encoded path,required"`
	BranchName string               `json:"branch_name" jsonschema:"New branch name (param 'branch_name' not 'branch' or 'name'),required"`
	Ref        string               `json:"ref"         jsonschema:"Branch name, tag, or commit SHA to create from,required"`
}

CreateInput defines parameters for creating a new branch.

type DeleteInput 

type DeleteInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"  jsonschema:"Project ID or URL-encoded path,required"`
	BranchName string               `json:"branch_name" jsonschema:"Branch name to delete,required"`
}

DeleteInput defines parameters for deleting a branch.

type DeleteMergedInput 

type DeleteMergedInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
}

DeleteMergedInput defines parameters for deleting all merged branches in a project.

type GetInput 

type GetInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"  jsonschema:"Project ID or URL-encoded path,required"`
	BranchName string               `json:"branch_name" jsonschema:"Branch name to retrieve (param 'branch_name' not 'branch'),required"`
}

GetInput defines parameters for retrieving a single branch.

type LastPipelineOutput added in v2.3.0 

type LastPipelineOutput = toolutil.LastPipelineOutput

LastPipelineOutput mirrors gl.PipelineInfo, the pipeline summary embedded in a commit payload as last_pipeline. Canonical shape shared via toolutil.

type ListInput 

type ListInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	Search    string               `json:"search,omitempty"   jsonschema:"Filter branches by name (substring match)"`
	Regex     string               `json:"regex,omitempty"    jsonschema:"Filter branches whose names match this regular expression"`
	OrderBy   string               `json:"order_by,omitempty" jsonschema:"Column to order results by (e.g. name, updated)"`
	Sort      string               `json:"sort,omitempty"     jsonschema:"Sort direction (asc, desc)"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListInput defines parameters for listing branches. It mirrors gl.ListBranchesOptions, including the regex filter and keyset pagination via the embedded gl.ListOptions (order_by, sort, pagination, page_token).

type ListOutput 

type ListOutput struct {
	toolutil.HintableOutput
	Branches   []Output                  `json:"branches"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

ListOutput holds a paginated list of branches.

func List 

func List(ctx context.Context, client *gitlabclient.Client, input ListInput) (ListOutput, error)

List retrieves a paginated list of branches for the specified GitLab project. An optional search filter restricts results by branch name substring.

type Output 

type Output struct {
	toolutil.HintableOutput
	Name               string        `json:"name"`
	Merged             bool          `json:"merged"`
	Protected          bool          `json:"protected"`
	Default            bool          `json:"default"`
	WebURL             string        `json:"web_url"`
	Commit             *CommitOutput `json:"commit,omitempty"`
	CanPush            bool          `json:"can_push"`
	DevelopersCanPush  bool          `json:"developers_can_push"`
	DevelopersCanMerge bool          `json:"developers_can_merge"`
}

Output represents a Git branch. It mirrors gl.Branch field-for-field, surfacing the full embedded commit object on the canonical commit key (C-IMPORTS).

func Create 

func Create(ctx context.Context, client *gitlabclient.Client, input CreateInput) (Output, error)

Create creates a new branch in the specified GitLab project from the given ref (branch, tag, or commit SHA). Returns the created branch details or an error if the ref does not exist or the branch already exists.

func Get 

func Get(ctx context.Context, client *gitlabclient.Client, input GetInput) (Output, error)

Get retrieves a single branch by name from a GitLab project.

func ToOutput 

func ToOutput(b *gl.Branch) Output

ToOutput converts a GitLab API gl.Branch to the MCP tool output format, surfacing the full embedded commit object when present.

type ProtectInput 

type ProtectInput struct {
	ProjectID                 toolutil.StringOrInt    `json:"project_id"                          jsonschema:"Project ID or URL-encoded path,required"`
	BranchName                string                  `json:"branch_name"                         jsonschema:"Branch name or wildcard (e.g. 'main' or 'release/*'),required"`
	PushAccessLevel           int                     `json:"push_access_level,omitempty"         jsonschema:"Access level for push (0=No access 30=Developer 40=Maintainer)"`
	MergeAccessLevel          int                     `json:"merge_access_level,omitempty"        jsonschema:"Access level for merge (0=No access 30=Developer 40=Maintainer)"`
	UnprotectAccessLevel      int                     `` /* 130-byte string literal not displayed */
	AllowForcePush            *bool                   `json:"allow_force_push,omitempty"          jsonschema:"Allow force push to this branch"`
	AllowedToPush             []BranchPermissionInput `` /* 134-byte string literal not displayed */
	AllowedToMerge            []BranchPermissionInput `` /* 135-byte string literal not displayed */
	AllowedToUnprotect        []BranchPermissionInput `` /* 139-byte string literal not displayed */
	CodeOwnerApprovalRequired *bool                   `` /* 131-byte string literal not displayed */
}

ProtectInput defines parameters for protecting a branch. It mirrors gl.ProtectRepositoryBranchesOptions, including the fine-grained allowed_to_{push,merge,unprotect} permission arrays (C-IMPORTS). The branch name or wildcard is accepted on branch_name (the SDK's name field).

type ProtectedGetInput 

type ProtectedGetInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"  jsonschema:"Project ID or URL-encoded path,required"`
	BranchName string               `json:"branch_name" jsonschema:"Name of the protected branch,required"`
}

ProtectedGetInput defines parameters for retrieving a single protected branch.

type ProtectedListInput 

type ProtectedListInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	Search    string               `json:"search,omitempty"   jsonschema:"Filter protected branches by name (substring match)"`
	OrderBy   string               `json:"order_by,omitempty" jsonschema:"Column to order results by (e.g. name)"`
	Sort      string               `json:"sort,omitempty"     jsonschema:"Sort direction (asc, desc)"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ProtectedListInput defines parameters for listing protected branches. It mirrors gl.ListProtectedBranchesOptions, including the search filter and keyset pagination via the embedded gl.ListOptions (order_by, sort, pagination, page_token).

type ProtectedListOutput 

type ProtectedListOutput struct {
	toolutil.HintableOutput
	Branches   []ProtectedOutput         `json:"branches"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

ProtectedListOutput holds the list of protected branches.

func ProtectedList 

func ProtectedList(ctx context.Context, client *gitlabclient.Client, input ProtectedListInput) (ProtectedListOutput, error)

ProtectedList retrieves a paginated list of protected branches for the specified GitLab project. Pagination parameters are forwarded to the API.

type ProtectedOutput 

type ProtectedOutput struct {
	toolutil.HintableOutput
	ID                        int64                           `json:"id"`
	Name                      string                          `json:"name"`
	PushAccessLevels          []BranchAccessDescriptionOutput `json:"push_access_levels,omitempty"`
	MergeAccessLevels         []BranchAccessDescriptionOutput `json:"merge_access_levels,omitempty"`
	UnprotectAccessLevels     []BranchAccessDescriptionOutput `json:"unprotect_access_levels,omitempty"`
	AllowForcePush            bool                            `json:"allow_force_push"`
	CodeOwnerApprovalRequired bool                            `json:"code_owner_approval_required"`
}

ProtectedOutput represents a protected branch. It mirrors gl.ProtectedBranch field-for-field, surfacing the full push/merge/unprotect access-level arrays on their canonical keys (C-IMPORTS).

func Protect 

func Protect(ctx context.Context, client *gitlabclient.Client, input ProtectInput) (ProtectedOutput, error)

Protect protects a branch in the specified GitLab project by calling the Protected Branches API. It configures push and merge access levels and optionally enables force push. Returns an error if the API call fails.

func ProtectedGet 

func ProtectedGet(ctx context.Context, client *gitlabclient.Client, input ProtectedGetInput) (ProtectedOutput, error)

ProtectedGet retrieves a single protected branch by name.

func ProtectedToOutput 

func ProtectedToOutput(b *gl.ProtectedBranch) ProtectedOutput

ProtectedToOutput converts a GitLab API gl.ProtectedBranch to the MCP tool output format, surfacing the full push/merge/unprotect access-level arrays.

func ProtectedUpdate 

func ProtectedUpdate(ctx context.Context, client *gitlabclient.Client, input ProtectedUpdateInput) (ProtectedOutput, error)

ProtectedUpdate updates settings on an existing protected branch.

type ProtectedUpdateInput 

type ProtectedUpdateInput struct {
	ProjectID                 toolutil.StringOrInt    `json:"project_id"                          jsonschema:"Project ID or URL-encoded path,required"`
	BranchName                string                  `json:"branch_name"                         jsonschema:"Name of the protected branch to update,required"`
	Name                      string                  `json:"name,omitempty"                      jsonschema:"New name or wildcard for the protected branch rule (rename)"`
	AllowForcePush            *bool                   `json:"allow_force_push,omitempty"          jsonschema:"Allow force push to this branch"`
	CodeOwnerApprovalRequired *bool                   `json:"code_owner_approval_required,omitempty" tier:"premium" jsonschema:"Require CODEOWNERS approval"`
	AllowedToPush             []BranchPermissionInput `` /* 134-byte string literal not displayed */
	AllowedToMerge            []BranchPermissionInput `` /* 135-byte string literal not displayed */
	AllowedToUnprotect        []BranchPermissionInput `` /* 139-byte string literal not displayed */
}

ProtectedUpdateInput defines parameters for updating a protected branch's settings. It mirrors gl.UpdateProtectedBranchOptions, including the rename (name) and the fine-grained allowed_to_{push,merge,unprotect} permission arrays (C-IMPORTS). The branch to update is identified by branch_name; the new name (when renaming the rule) is supplied via the name field.

type UnprotectInput 

type UnprotectInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"  jsonschema:"Project ID or URL-encoded path,required"`
	BranchName string               `json:"branch_name" jsonschema:"Name of the protected branch to remove,required"`
}

UnprotectInput defines parameters for unprotecting a branch.

type UnprotectOutput 

type UnprotectOutput struct {
	toolutil.HintableOutput
	Status  string `json:"status"`
	Message string `json:"message"`
}

UnprotectOutput holds the result of an unprotect operation.

func Unprotect 

func Unprotect(ctx context.Context, client *gitlabclient.Client, input UnprotectInput) (UnprotectOutput, error)

Unprotect removes protection from a branch in the specified GitLab project. The operation is idempotent: if the branch is not protected, it returns success with an informational message instead of an error.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.