epics

package
v2.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package epics implements MCP tools for GitLab epic operations.

The package wraps the GitLab Epics API:

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 group epic actions.

func Delete 

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

Delete permanently removes an epic using the Work Items API.

func DeleteOutput 

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

DeleteOutput deletes an epic and returns the canonical success message shape.

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.

Types

type BasicUserOutput added in v2.3.0 

type BasicUserOutput struct {
	ID        int64  `json:"id"`
	Username  string `json:"username"`
	Name      string `json:"name,omitempty"`
	State     string `json:"state,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	WebURL    string `json:"web_url,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
}

BasicUserOutput mirrors gl.BasicUser (and the compatible gl.EpicAuthor), the compact user object embedded on the epic author and assignees keys. Per the 1:1 audit policy (full nested objects, C-IMPORTS) the SDK sub-object is replicated here rather than imported from a sibling package to preserve the zero-import-cycle constraint.

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:"epic_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:"epic_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:"epic_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"`
	GroupID      int64            `json:"group_id,omitempty"`
	ParentID     int64            `json:"parent_id,omitempty"`
	Title        string           `json:"title"`
	Description  string           `json:"description,omitempty"`
	State        string           `json:"state"`
	WebURL       string           `json:"web_url,omitempty"`
	URL          string           `json:"url,omitempty"`
	Author       *BasicUserOutput `json:"author,omitempty"`
	Labels       []string         `json:"labels,omitempty"`
	Confidential bool             `json:"confidential,omitempty"`

	StartDate               string `json:"start_date,omitempty"`
	StartDateIsFixed        bool   `json:"start_date_is_fixed,omitempty"`
	StartDateFixed          string `json:"start_date_fixed,omitempty"`
	StartDateFromMilestones string `json:"start_date_from_milestones,omitempty"`
	DueDate                 string `json:"due_date,omitempty"`
	DueDateIsFixed          bool   `json:"due_date_is_fixed,omitempty"`
	DueDateFixed            string `json:"due_date_fixed,omitempty"`
	DueDateFromMilestones   string `json:"due_date_from_milestones,omitempty"`

	Upvotes        int64  `json:"upvotes,omitempty"`
	Downvotes      int64  `json:"downvotes,omitempty"`
	UserNotesCount int64  `json:"user_notes_count,omitempty"`
	CreatedAt      string `json:"created_at,omitempty"`
	UpdatedAt      string `json:"updated_at,omitempty"`
	ClosedAt       string `json:"closed_at,omitempty"`
}

LinksItem is the child-epic output for the GetLinks REST endpoint, mirroring gl.Epic. Per the 1:1 audit policy it surfaces every gl.Epic field; the author is a full nested object.

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"`
	AuthorID           *int64   `json:"author_id,omitempty" jsonschema:"Filter by author user ID"`
	LabelName          []string `json:"label_name,omitempty" jsonschema:"Filter by label names"`
	MyReactionEmoji    string   `` /* 131-byte string literal not displayed */
	Confidential       *bool    `json:"confidential,omitempty" jsonschema:"Filter by confidentiality"`
	OrderBy            string   `json:"order_by,omitempty" jsonschema:"Order epics by field (created_at, updated_at, title)"`
	Sort               string   `json:"sort,omitempty" jsonschema:"Sort order (asc or desc)"`
	CreatedAfter       string   `json:"created_after,omitempty" jsonschema:"Return epics created after date (ISO 8601, e.g. 2025-01-01T00:00:00Z)"`
	CreatedBefore      string   `json:"created_before,omitempty" jsonschema:"Return epics created before date (ISO 8601, e.g. 2025-12-31T23:59:59Z)"`
	UpdatedAfter       string   `json:"updated_after,omitempty" jsonschema:"Return epics updated on or after date (ISO 8601, e.g. 2025-01-01T00:00:00Z)"`
	UpdatedBefore      string   `json:"updated_before,omitempty" jsonschema:"Return epics updated on or before date (ISO 8601, e.g. 2025-12-31T23:59:59Z)"`
	WithLabelsDetails  *bool    `` /* 140-byte string literal not displayed */
	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"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

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"`
	URL          string             `json:"url,omitempty"`
	GroupID      int64              `json:"group_id,omitempty"`
	ParentID     int64              `json:"parent_id,omitempty"`
	Author       *BasicUserOutput   `json:"author,omitempty"`
	Assignees    []*BasicUserOutput `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"`
	StartDateIsFixed        bool   `json:"start_date_is_fixed,omitempty"`
	StartDateFixed          string `json:"start_date_fixed,omitempty"`
	StartDateFromMilestones string `json:"start_date_from_milestones,omitempty"`
	DueDate                 string `json:"due_date,omitempty"`
	DueDateIsFixed          bool   `json:"due_date_is_fixed,omitempty"`
	DueDateFixed            string `json:"due_date_fixed,omitempty"`
	DueDateFromMilestones   string `json:"due_date_from_milestones,omitempty"`

	HealthStatus   string `json:"health_status,omitempty"`
	Weight         *int64 `json:"weight,omitempty"`
	Upvotes        int64  `json:"upvotes,omitempty"`
	Downvotes      int64  `json:"downvotes,omitempty"`
	UserNotesCount int64  `json:"user_notes_count,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, or by the REST gl.Epic for the child-epic links endpoint). Per the 1:1 audit policy it carries the union of fields exposed by gl.WorkItem and gl.Epic; fields absent on a given source stay at their zero value.

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:"epic_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.