epics

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package epics implements GitLab group epic operations using the Work Items GraphQL API. Epics are high-level planning items attached to groups.

This package was migrated from the deprecated Epics REST API (deprecated GitLab 17.0, removal planned 19.0) to the Work Items GraphQL API per ADR-0009 (progressive GraphQL migration).

The GetLinks handler remains on REST because client-go v2 does not yet expose a GraphQL query for work item children.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Delete 

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

Delete permanently removes an epic using the Work Items API.

func FormatLinksMarkdown 

func FormatLinksMarkdown(out LinksOutput) string

FormatLinksMarkdown renders child epics as a Markdown table.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a list of epics as a Markdown table.

func FormatOutputMarkdown 

func FormatOutputMarkdown(e Output) string

FormatOutputMarkdown renders a single epic as a Markdown summary.

func RegisterTools 

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

RegisterTools registers MCP tools for GitLab group epic operations.

Types

type CreateInput 

type CreateInput struct {
	FullPath     string  `json:"full_path" jsonschema:"Full path of the group (e.g. my-group),required"`
	Title        string  `json:"title" jsonschema:"Epic title,required"`
	Description  string  `json:"description,omitempty" jsonschema:"Epic description (Markdown supported)"`
	Confidential *bool   `json:"confidential,omitempty" jsonschema:"Whether the epic is confidential"`
	Color        string  `json:"color,omitempty" jsonschema:"Epic color (hex format, e.g. #FF0000)"`
	StartDate    string  `json:"start_date,omitempty" jsonschema:"Start date (YYYY-MM-DD)"`
	DueDate      string  `json:"due_date,omitempty" jsonschema:"Due date (YYYY-MM-DD)"`
	AssigneeIDs  []int64 `json:"assignee_ids,omitempty" jsonschema:"Global IDs of assignees"`
	LabelIDs     []int64 `json:"label_ids,omitempty" jsonschema:"Global IDs of labels"`
	Weight       *int64  `json:"weight,omitempty" jsonschema:"Weight of the epic"`
	HealthStatus string  `json:"health_status,omitempty" jsonschema:"Health status (onTrack/needsAttention/atRisk)"`
}

CreateInput defines parameters for creating a new epic.

type DeleteInput 

type DeleteInput struct {
	FullPath string `json:"full_path" jsonschema:"Full path of the group (e.g. my-group),required"`
	IID      int64  `json:"iid" jsonschema:"Epic IID within the group,required"`
}

DeleteInput defines parameters for deleting an epic.

type GetInput 

type GetInput struct {
	FullPath string `json:"full_path" jsonschema:"Full path of the group (e.g. my-group),required"`
	IID      int64  `json:"iid" jsonschema:"Epic IID within the group,required"`
}

GetInput defines parameters for getting a single epic.

type GetLinksInput 

type GetLinksInput struct {
	FullPath string `json:"full_path" jsonschema:"Full path of the group (e.g. my-group),required"`
	IID      int64  `json:"iid" jsonschema:"Epic IID within the group,required"`
}

GetLinksInput defines parameters for listing child epics (REST).

type LinkedItem 

type LinkedItem struct {
	IID      int64  `json:"iid"`
	LinkType string `json:"link_type"`
	Path     string `json:"path,omitempty"`
}

LinkedItem represents a linked work item summary.

type LinksItem 

type LinksItem struct {
	ID           int64    `json:"id"`
	IID          int64    `json:"iid"`
	Title        string   `json:"title"`
	State        string   `json:"state"`
	WebURL       string   `json:"web_url,omitempty"`
	Author       string   `json:"author,omitempty"`
	Labels       []string `json:"labels,omitempty"`
	Confidential bool     `json:"confidential,omitempty"`
	CreatedAt    string   `json:"created_at,omitempty"`
}

LinksItem is a simplified epic output for the GetLinks REST endpoint.

type LinksOutput 

type LinksOutput struct {
	toolutil.HintableOutput
	ChildEpics []LinksItem `json:"child_epics"`
}

LinksOutput holds child epics of a parent epic (REST-backed). 

func GetLinks(ctx context.Context, client *gitlabclient.Client, input GetLinksInput) (LinksOutput, error)

GetLinks retrieves all child epics of a parent epic. This handler uses the REST API because client-go v2 does not yet expose a GraphQL query for work item children.

type ListInput 

type ListInput struct {
	FullPath           string   `json:"full_path" jsonschema:"Full path of the group (e.g. my-group or my-group/sub-group),required"`
	State              string   `json:"state,omitempty" jsonschema:"Filter by state (opened/closed/all)"`
	Search             string   `json:"search,omitempty" jsonschema:"Search in title and description"`
	AuthorUsername     string   `json:"author_username,omitempty" jsonschema:"Filter by author username"`
	LabelName          []string `json:"label_name,omitempty" jsonschema:"Filter by label names"`
	Confidential       *bool    `json:"confidential,omitempty" jsonschema:"Filter by confidentiality"`
	Sort               string   `json:"sort,omitempty" jsonschema:"Sort order"`
	First              *int64   `json:"first,omitempty" jsonschema:"Number of items to return (cursor-based pagination)"`
	After              string   `json:"after,omitempty" jsonschema:"Cursor for forward pagination"`
	IncludeAncestors   *bool    `json:"include_ancestors,omitempty" jsonschema:"Include epics from ancestor groups"`
	IncludeDescendants *bool    `json:"include_descendants,omitempty" jsonschema:"Include epics from descendant groups"`
}

ListInput defines parameters for listing group epics via Work Items API.

type ListOutput 

type ListOutput struct {
	toolutil.HintableOutput
	Epics []Output `json:"epics"`
}

ListOutput holds a list of epics with cursor-based pagination info.

func List 

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

List retrieves epics for a group using the Work Items API with type filter.

type Output 

type Output struct {
	toolutil.HintableOutput
	ID           int64        `json:"id"`
	IID          int64        `json:"iid"`
	Type         string       `json:"type"`
	State        string       `json:"state"`
	Status       string       `json:"status,omitempty"`
	Title        string       `json:"title"`
	Description  string       `json:"description,omitempty"`
	WebURL       string       `json:"web_url,omitempty"`
	Author       string       `json:"author,omitempty"`
	Assignees    []string     `json:"assignees,omitempty"`
	Labels       []string     `json:"labels,omitempty"`
	LinkedItems  []LinkedItem `json:"linked_items,omitempty"`
	Confidential bool         `json:"confidential,omitempty"`
	Color        string       `json:"color,omitempty"`
	StartDate    string       `json:"start_date,omitempty"`
	DueDate      string       `json:"due_date,omitempty"`
	HealthStatus string       `json:"health_status,omitempty"`
	Weight       *int64       `json:"weight,omitempty"`
	ParentIID    int64        `json:"parent_iid,omitempty"`
	ParentPath   string       `json:"parent_path,omitempty"`
	CreatedAt    string       `json:"created_at,omitempty"`
	UpdatedAt    string       `json:"updated_at,omitempty"`
	ClosedAt     string       `json:"closed_at,omitempty"`
}

Output represents a single epic (backed by a Work Item of type Epic).

func Create 

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

Create creates a new epic using the Work Items API with the Epic type.

func Get 

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

Get retrieves a single epic by its IID using the Work Items API.

func Update 

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

Update modifies an existing epic using the Work Items API.

type UpdateInput 

type UpdateInput struct {
	FullPath       string  `json:"full_path" jsonschema:"Full path of the group (e.g. my-group),required"`
	IID            int64   `json:"iid" jsonschema:"Epic IID within the group,required"`
	Title          string  `json:"title,omitempty" jsonschema:"Updated epic title"`
	Description    string  `json:"description,omitempty" jsonschema:"Updated description (Markdown supported)"`
	StateEvent     string  `json:"state_event,omitempty" jsonschema:"State event: CLOSE or REOPEN"`
	ParentID       *int64  `json:"parent_id,omitempty" jsonschema:"Global ID of the parent epic work item"`
	Color          string  `json:"color,omitempty" jsonschema:"Epic color (hex format)"`
	StartDate      string  `json:"start_date,omitempty" jsonschema:"Start date (YYYY-MM-DD)"`
	DueDate        string  `json:"due_date,omitempty" jsonschema:"Due date (YYYY-MM-DD)"`
	AddLabelIDs    []int64 `json:"add_label_ids,omitempty" jsonschema:"Global IDs of labels to add"`
	RemoveLabelIDs []int64 `json:"remove_label_ids,omitempty" jsonschema:"Global IDs of labels to remove"`
	AssigneeIDs    []int64 `json:"assignee_ids,omitempty" jsonschema:"Global IDs of assignees (empty array to remove all)"`
	Weight         *int64  `json:"weight,omitempty" jsonschema:"Weight of the epic"`
	HealthStatus   string  `json:"health_status,omitempty" jsonschema:"Health status (onTrack/needsAttention/atRisk)"`
	Status         string  `json:"status,omitempty" jsonschema:"Work item status: TODO, IN_PROGRESS, DONE, WONT_DO, or DUPLICATE"`
}

UpdateInput defines parameters for updating an existing epic.

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.