groups

package
v1.0.5 Latest Latest
Warning

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

 Go to latest Published: Apr 22, 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.

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"`
	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 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.