groups

package
v1.4.2 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package groups implements MCP tool handlers for GitLab group operations including list, get, list members, and list subgroups (descendant groups). It wraps the Groups service from client-go v2.

hooks.go implements GitLab group webhook operations including list, get, add, edit, and delete. It exposes typed input/output structs and handler functions that interact with the GitLab Group Webhooks API v4.

markdown.go provides Markdown formatting functions for group MCP tool output.

register.go wires groups MCP tools to the MCP server.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Archive 

func Archive(ctx context.Context, client *gitlabclient.Client, input ArchiveInput) error

Archive archives a GitLab group. Requires Owner role or administrator.

func Delete 

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

Delete removes a GitLab group.

func DeleteHook 

func DeleteHook(ctx context.Context, client *gitlabclient.Client, input DeleteHookInput) error

DeleteHook removes a webhook from a group.

func FormatHookListMarkdown 

func FormatHookListMarkdown(out HookListOutput) string

FormatHookListMarkdown renders a paginated list of group hooks as a Markdown table.

func FormatHookMarkdown 

func FormatHookMarkdown(h HookOutput) string

FormatHookMarkdown renders a single group hook as a Markdown summary.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a list of groups as a Markdown table.

func FormatListProjectsMarkdown 

func FormatListProjectsMarkdown(out ListProjectsOutput) string

FormatListProjectsMarkdown renders a list of group projects as a Markdown table.

func FormatMemberListMarkdown 

func FormatMemberListMarkdown(out MemberListOutput) string

FormatMemberListMarkdown renders a list of group members as a Markdown table.

func FormatOutputMarkdown 

func FormatOutputMarkdown(g Output) string

FormatOutputMarkdown renders a single group as a Markdown summary.

func RegisterTools 

func RegisterTools(server *mcp.Server, client *gitlabclient.Client)

RegisterTools registers tools for group list, get, members, and subgroups.

func Unarchive 

func Unarchive(ctx context.Context, client *gitlabclient.Client, input ArchiveInput) error

Unarchive unarchives a GitLab group. Requires Owner role or administrator.

Types

type AddHookInput 

type AddHookInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	HookInput
}

AddHookInput defines parameters for adding a new group hook.

type ArchiveInput 

type ArchiveInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
}

ArchiveInput defines parameters for archiving or unarchiving a group.

type CreateInput 

type CreateInput struct {
	Name                 string `json:"name"                          jsonschema:"Group name,required"`
	Path                 string `json:"path,omitempty"                jsonschema:"Group URL path (defaults to kebab-case of name)"`
	Description          string `json:"description,omitempty"         jsonschema:"Group description"`
	Visibility           string `json:"visibility,omitempty"          jsonschema:"Visibility level (private, internal, public)"`
	ParentID             int64  `json:"parent_id,omitempty"           jsonschema:"Parent group ID (creates a subgroup)"`
	RequestAccessEnabled *bool  `json:"request_access_enabled,omitempty" jsonschema:"Allow users to request access"`
	LFSEnabled           *bool  `json:"lfs_enabled,omitempty"         jsonschema:"Enable Git LFS"`
	DefaultBranch        string `json:"default_branch,omitempty"      jsonschema:"Default branch name"`
}

CreateInput defines parameters for creating a group.

type DeleteHookInput 

type DeleteHookInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	HookID  int64                `json:"hook_id"  jsonschema:"Hook ID to delete,required"`
}

DeleteHookInput defines parameters for deleting a group hook.

type DeleteInput 

type DeleteInput struct {
	GroupID           toolutil.StringOrInt `json:"group_id"                    jsonschema:"Group ID or URL-encoded path,required"`
	PermanentlyRemove bool                 `json:"permanently_remove,omitempty" jsonschema:"Permanently remove instead of marking for deletion"`
	FullPath          string               `json:"full_path,omitempty"          jsonschema:"Full path (required when permanently_remove=true)"`
}

DeleteInput defines parameters for deleting a group.

type EditHookInput 

type EditHookInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	HookID  int64                `json:"hook_id"  jsonschema:"Hook ID to edit,required"`
	HookInput
}

EditHookInput defines parameters for editing an existing group hook.

type GetHookInput 

type GetHookInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	HookID  int64                `json:"hook_id"  jsonschema:"Hook ID,required"`
}

GetHookInput defines parameters for retrieving a single group hook.

type GetInput 

type GetInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
}

GetInput defines parameters for retrieving a single group.

type HookInput 

type HookInput struct {
	URL                      string `json:"url,omitempty"                        jsonschema:"Webhook URL (required for add)"`
	Name                     string `json:"name,omitempty"                       jsonschema:"Hook name"`
	Description              string `json:"description,omitempty"                jsonschema:"Hook description"`
	Token                    string `json:"token,omitempty"                      jsonschema:"Secret token for payload validation"`
	PushEvents               *bool  `json:"push_events,omitempty"                jsonschema:"Trigger on push events"`
	TagPushEvents            *bool  `json:"tag_push_events,omitempty"            jsonschema:"Trigger on tag push events"`
	MergeRequestsEvents      *bool  `json:"merge_requests_events,omitempty"      jsonschema:"Trigger on merge request events"`
	IssuesEvents             *bool  `json:"issues_events,omitempty"              jsonschema:"Trigger on issue events"`
	NoteEvents               *bool  `json:"note_events,omitempty"                jsonschema:"Trigger on comment events"`
	JobEvents                *bool  `json:"job_events,omitempty"                 jsonschema:"Trigger on job events"`
	PipelineEvents           *bool  `json:"pipeline_events,omitempty"            jsonschema:"Trigger on pipeline events"`
	WikiPageEvents           *bool  `json:"wiki_page_events,omitempty"           jsonschema:"Trigger on wiki page events"`
	DeploymentEvents         *bool  `json:"deployment_events,omitempty"          jsonschema:"Trigger on deployment events"`
	ReleasesEvents           *bool  `json:"releases_events,omitempty"            jsonschema:"Trigger on release events"`
	SubGroupEvents           *bool  `json:"subgroup_events,omitempty"            jsonschema:"Trigger on subgroup events"`
	MemberEvents             *bool  `json:"member_events,omitempty"              jsonschema:"Trigger on member events"`
	ConfidentialIssuesEvents *bool  `json:"confidential_issues_events,omitempty" jsonschema:"Trigger on confidential issue events"`
	ConfidentialNoteEvents   *bool  `json:"confidential_note_events,omitempty"   jsonschema:"Trigger on confidential note events"`
	EnableSSLVerification    *bool  `json:"enable_ssl_verification,omitempty"    jsonschema:"Enable SSL verification for the hook endpoint"`
	PushEventsBranchFilter   string `json:"push_events_branch_filter,omitempty"  jsonschema:"Branch filter for push events (e.g. 'main')"`
}

HookInput defines common parameters for creating or editing a group hook.

type HookListOutput 

type HookListOutput struct {
	toolutil.HintableOutput
	Hooks      []HookOutput              `json:"hooks"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

HookListOutput holds a paginated list of group hooks.

func ListHooks 

func ListHooks(ctx context.Context, client *gitlabclient.Client, input ListHooksInput) (HookListOutput, error)

ListHooks retrieves a paginated list of webhooks for a group.

type HookOutput 

type HookOutput struct {
	toolutil.HintableOutput
	ID                       int64             `json:"id"`
	URL                      string            `json:"url"`
	Name                     string            `json:"name,omitempty"`
	Description              string            `json:"description,omitempty"`
	GroupID                  int64             `json:"group_id"`
	PushEvents               bool              `json:"push_events"`
	TagPushEvents            bool              `json:"tag_push_events"`
	MergeRequestsEvents      bool              `json:"merge_requests_events"`
	IssuesEvents             bool              `json:"issues_events"`
	NoteEvents               bool              `json:"note_events"`
	JobEvents                bool              `json:"job_events"`
	PipelineEvents           bool              `json:"pipeline_events"`
	WikiPageEvents           bool              `json:"wiki_page_events"`
	DeploymentEvents         bool              `json:"deployment_events"`
	ReleasesEvents           bool              `json:"releases_events"`
	SubGroupEvents           bool              `json:"subgroup_events"`
	MemberEvents             bool              `json:"member_events"`
	ConfidentialIssuesEvents bool              `json:"confidential_issues_events"`
	ConfidentialNoteEvents   bool              `json:"confidential_note_events"`
	EnableSSLVerification    bool              `json:"enable_ssl_verification"`
	AlertStatus              string            `json:"alert_status,omitempty"`
	URLVariables             []HookURLVariable `json:"url_variables,omitempty"`
	CreatedAt                string            `json:"created_at,omitempty"`
}

HookOutput represents a GitLab group webhook.

func AddHook 

func AddHook(ctx context.Context, client *gitlabclient.Client, input AddHookInput) (HookOutput, error)

AddHook adds a new webhook to a group. Requires the webhook URL.

func EditHook 

func EditHook(ctx context.Context, client *gitlabclient.Client, input EditHookInput) (HookOutput, error)

EditHook updates an existing group webhook configuration.

func GetHook 

func GetHook(ctx context.Context, client *gitlabclient.Client, input GetHookInput) (HookOutput, error)

GetHook retrieves a single group webhook by its ID.

type HookURLVariable added in v1.3.3 

type HookURLVariable struct {
	Key   string `json:"key"`
	Value string `json:"value,omitempty"`
}

HookURLVariable represents a templated webhook URL variable used to substitute placeholders like {var_name} in a webhook URL with secret values resolved server-side. Only the key is returned by the API; the value is masked.

type ListHooksInput 

type ListHooksInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	toolutil.PaginationInput
}

ListHooksInput defines parameters for listing group hooks.

type ListInput 

type ListInput struct {
	Search               string  `json:"search,omitempty"                jsonschema:"Filter groups by name or path"`
	Owned                bool    `json:"owned,omitempty"                 jsonschema:"Limit to groups explicitly owned by the authenticated user"`
	TopLevelOnly         bool    `json:"top_level_only,omitempty"        jsonschema:"Limit to top-level groups (exclude subgroups)"`
	OrderBy              string  `json:"order_by,omitempty"              jsonschema:"Order groups by field (name, path, id, similarity)"`
	Sort                 string  `json:"sort,omitempty"                  jsonschema:"Sort direction (asc, desc)"`
	Visibility           string  `json:"visibility,omitempty"            jsonschema:"Filter by visibility (public, internal, private)"`
	AllAvailable         bool    `json:"all_available,omitempty"         jsonschema:"Show all groups accessible by the authenticated user"`
	Statistics           bool    `json:"statistics,omitempty"            jsonschema:"Include group statistics (storage, counts)"`
	WithCustomAttributes bool    `json:"with_custom_attributes,omitempty" jsonschema:"Include custom attributes in the response"`
	SkipGroups           []int64 `json:"skip_groups,omitempty"           jsonschema:"Group IDs to exclude from results"`
	toolutil.PaginationInput
}

ListInput defines parameters for listing groups.

type ListOutput 

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

ListOutput holds a paginated list of groups.

func List 

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

List retrieves a paginated list of GitLab groups visible to the authenticated user. Supports filtering by search term, ownership, and top-level-only restriction. Returns the groups with pagination metadata. 

func Search(ctx context.Context, client *gitlabclient.Client, input SearchInput) (ListOutput, error)

Search searches for groups by query string.

func SubgroupsList 

func SubgroupsList(ctx context.Context, client *gitlabclient.Client, input SubgroupsListInput) (ListOutput, error)

SubgroupsList retrieves a paginated list of descendant groups (subgroups) for a given parent group. Supports filtering by search term and pagination. Returns the subgroups with pagination metadata.

type ListProjectsInput 

type ListProjectsInput struct {
	GroupID          toolutil.StringOrInt `json:"group_id"                  jsonschema:"Group ID or URL-encoded path,required"`
	Search           string               `json:"search,omitempty"          jsonschema:"Filter projects by name"`
	Archived         *bool                `json:"archived,omitempty"        jsonschema:"Filter archived projects"`
	Visibility       string               `json:"visibility,omitempty"      jsonschema:"Filter by visibility (public, internal, private)"`
	OrderBy          string               `` /* 131-byte string literal not displayed */
	Sort             string               `json:"sort,omitempty"            jsonschema:"Sort direction (asc, desc)"`
	Simple           bool                 `json:"simple,omitempty"          jsonschema:"Return limited fields"`
	Owned            bool                 `json:"owned,omitempty"           jsonschema:"Limit to projects owned by current user"`
	Starred          bool                 `json:"starred,omitempty"         jsonschema:"Limit to starred projects"`
	IncludeSubGroups bool                 `json:"include_subgroups,omitempty" jsonschema:"Include projects in subgroups"`
	WithShared       *bool                `json:"with_shared,omitempty"     jsonschema:"Include shared projects"`
	toolutil.PaginationInput
}

ListProjectsInput defines parameters for listing group projects.

type ListProjectsOutput 

type ListProjectsOutput struct {
	toolutil.HintableOutput
	Projects   []ProjectItem             `json:"projects"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

ListProjectsOutput holds a paginated list of group projects.

func ListProjects 

func ListProjects(ctx context.Context, client *gitlabclient.Client, input ListProjectsInput) (ListProjectsOutput, error)

ListProjects retrieves projects belonging to a group.

type MemberListOutput 

type MemberListOutput struct {
	toolutil.HintableOutput
	Members    []MemberOutput            `json:"members"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

MemberListOutput holds a paginated list of group members.

func MembersList 

func MembersList(ctx context.Context, client *gitlabclient.Client, input MembersListInput) (MemberListOutput, error)

MembersList retrieves all members of a GitLab group, including inherited members from parent groups. Supports filtering by name or username and pagination. Returns the member list with pagination metadata.

type MemberOutput 

type MemberOutput struct {
	ID                     int64  `json:"id"`
	Username               string `json:"username"`
	Name                   string `json:"name"`
	State                  string `json:"state"`
	AvatarURL              string `json:"avatar_url,omitempty"`
	AccessLevel            int    `json:"access_level"`
	AccessLevelDescription string `json:"access_level_description"`
	WebURL                 string `json:"web_url"`
	CreatedAt              string `json:"created_at,omitempty"`
	ExpiresAt              string `json:"expires_at,omitempty"`
	Email                  string `json:"email,omitempty"`
	GroupSAMLProvider      string `json:"group_saml_provider,omitempty"`
	MemberRoleName         string `json:"member_role_name,omitempty"`
}

MemberOutput represents a GitLab group member.

func MemberToOutput 

func MemberToOutput(m *gl.GroupMember) MemberOutput

MemberToOutput converts a GitLab API gl.GroupMember to the MCP tool output format, including a human-readable access level description.

type MembersListInput 

type MembersListInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	Query   string               `json:"query,omitempty" jsonschema:"Filter members by name or username"`
	toolutil.PaginationInput
}

MembersListInput defines parameters for listing group members.

type Output 

type Output struct {
	toolutil.HintableOutput
	ID                    int64  `json:"id"`
	Name                  string `json:"name"`
	Path                  string `json:"path"`
	FullPath              string `json:"full_path"`
	FullName              string `json:"full_name,omitempty"`
	Description           string `json:"description,omitempty"`
	Visibility            string `json:"visibility"`
	WebURL                string `json:"web_url"`
	ParentID              int64  `json:"parent_id,omitempty"`
	DefaultBranch         string `json:"default_branch,omitempty"`
	RequestAccessEnabled  bool   `json:"request_access_enabled"`
	CreatedAt             string `json:"created_at,omitempty"`
	MarkedForDeletion     string `json:"marked_for_deletion_on,omitempty"`
	AvatarURL             string `json:"avatar_url,omitempty"`
	ProjectCreationLevel  string `json:"project_creation_level,omitempty"`
	SubGroupCreationLevel string `json:"subgroup_creation_level,omitempty"`
	LFSEnabled            bool   `json:"lfs_enabled"`
	SharedRunnersSetting  string `json:"shared_runners_setting,omitempty"`
}

Output represents a GitLab group.

func Create 

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

Create creates a new GitLab group.

func Get 

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

Get retrieves a single GitLab group by its ID or URL-encoded path. Returns the group details or an error if the group is not found.

func Restore 

func Restore(ctx context.Context, client *gitlabclient.Client, input RestoreInput) (Output, error)

Restore restores a group that was marked for deletion.

func ToOutput 

func ToOutput(g *gl.Group) Output

ToOutput converts a GitLab API gl.Group to the MCP tool output format, extracting identifier, path, visibility, and parent information.

func TransferProject 

func TransferProject(ctx context.Context, client *gitlabclient.Client, input TransferInput) (Output, error)

TransferProject transfers a project into the group namespace.

func Update 

func Update(ctx context.Context, client *gitlabclient.Client, input UpdateInput) (Output, error)

Update modifies an existing GitLab group.

type ProjectItem 

type ProjectItem struct {
	ID                int64  `json:"id"`
	Name              string `json:"name"`
	PathWithNamespace string `json:"path_with_namespace"`
	Description       string `json:"description,omitempty"`
	Visibility        string `json:"visibility"`
	WebURL            string `json:"web_url"`
	DefaultBranch     string `json:"default_branch,omitempty"`
	Archived          bool   `json:"archived"`
	CreatedAt         string `json:"created_at,omitempty"`
}

ProjectItem is a simplified project representation for group context.

type RestoreInput 

type RestoreInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
}

RestoreInput defines parameters for restoring a group marked for deletion.

type SearchInput 

type SearchInput struct {
	Query string `json:"query" jsonschema:"Search query string,required"`
}

SearchInput defines parameters for searching groups.

type SubgroupsListInput 

type SubgroupsListInput struct {
	GroupID        toolutil.StringOrInt `json:"group_id"                jsonschema:"Group ID or URL-encoded path,required"`
	Search         string               `json:"search,omitempty"        jsonschema:"Filter subgroups by name or path"`
	AllAvailable   bool                 `json:"all_available,omitempty" jsonschema:"Show all subgroups accessible by the authenticated user"`
	Owned          bool                 `json:"owned,omitempty"         jsonschema:"Limit to subgroups explicitly owned by the authenticated user"`
	MinAccessLevel int                  `` /* 126-byte string literal not displayed */
	OrderBy        string               `json:"order_by,omitempty"      jsonschema:"Order subgroups by field (name, path, id, similarity)"`
	Sort           string               `json:"sort,omitempty"          jsonschema:"Sort direction (asc, desc)"`
	Statistics     bool                 `json:"statistics,omitempty"    jsonschema:"Include group statistics (storage, counts)"`
	toolutil.PaginationInput
}

SubgroupsListInput defines parameters for listing subgroups.

type TransferInput 

type TransferInput struct {
	GroupID   toolutil.StringOrInt `json:"group_id"    jsonschema:"Group ID or URL-encoded path,required"`
	ProjectID toolutil.StringOrInt `json:"project_id"  jsonschema:"Project ID or URL-encoded path to transfer,required"`
}

TransferInput defines parameters for transferring a project to a group.

type UpdateInput 

type UpdateInput struct {
	GroupID              toolutil.StringOrInt `json:"group_id"                jsonschema:"Group ID or URL-encoded path,required"`
	Name                 string               `json:"name,omitempty"          jsonschema:"Group name"`
	Path                 string               `json:"path,omitempty"          jsonschema:"Group URL path"`
	Description          string               `json:"description,omitempty"   jsonschema:"Group description"`
	Visibility           string               `json:"visibility,omitempty"    jsonschema:"Visibility level (private, internal, public)"`
	RequestAccessEnabled *bool                `json:"request_access_enabled,omitempty" jsonschema:"Allow users to request access"`
	LFSEnabled           *bool                `json:"lfs_enabled,omitempty"   jsonschema:"Enable Git LFS"`
	DefaultBranch        string               `json:"default_branch,omitempty" jsonschema:"Default branch name"`
}

UpdateInput defines parameters for updating a group.

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.