workitemsavedviews

package
v3.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 10, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package workitemsavedviews implements MCP tools for GitLab work item saved views through the GraphQL API.

A saved view stores a named, reusable work item filter under a namespace: the filter itself, the sort order, and the display settings the consuming UI renders it with. The package lists, reads, creates, updates, deletes, subscribes to, and unsubscribes from saved views, and renders the results as Markdown.

The package wraps the GitLab GraphQL saved view query and mutations:

Experimental: upstream marks the Work Item Saved Views API as a work in progress that may introduce breaking changes even between minor versions.

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 work item saved view actions exposed through gitlab_issue.

func Delete 

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

Delete permanently removes a saved view.

func FormatGetMarkdown 

func FormatGetMarkdown(out GetOutput) string

FormatGetMarkdown renders one saved view, filters included.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a page of saved views as a Markdown table.

func FormatMutateMarkdown 

func FormatMutateMarkdown(out MutateOutput) string

FormatMutateMarkdown renders the confirmation shared by create, update, subscribe, and unsubscribe.

Types

type CreateInput 

type CreateInput struct {
	NamespacePath   string         `json:"namespace_path"             jsonschema:"Full path of the group or project to create the saved view under,required"`
	Name            string         `json:"name"                       jsonschema:"Name of the saved view,required"`
	Description     string         `json:"description,omitempty"      jsonschema:"Description of the saved view"`
	IsPrivate       *bool          `json:"is_private,omitempty"       jsonschema:"Keep the view private to the creating user. Defaults to true when omitted"`
	Filters         *Filters       `json:"filters,omitempty"          jsonschema:"Filters the view applies. Omit for a view with no filters"`
	Sort            string         `` /* 144-byte string literal not displayed */
	DisplaySettings map[string]any `` /* 301-byte string literal not displayed */
}

CreateInput holds the fields of a new saved view. It mirrors gl.CreateWorkItemSavedViewOptions.

type CustomFieldFilter 

type CustomFieldFilter struct {
	CustomFieldID        string   `json:"custom_field_id,omitempty"        jsonschema:"Custom field global ID"`
	CustomFieldName      string   `json:"custom_field_name,omitempty"      jsonschema:"Custom field name"`
	SelectedOptionIDs    []string `json:"selected_option_ids,omitempty"    jsonschema:"Selected option global IDs to match"`
	SelectedOptionValues []string `json:"selected_option_values,omitempty" jsonschema:"Selected option values to match"`
}

CustomFieldFilter mirrors gl.WorkItemCustomFieldFilter, which filters work items by one custom field value.

GitLab API docs: https://docs.gitlab.com/api/graphql/reference/#workitemwidgetcustomfieldfilterinputtype

type DeleteInput 

type DeleteInput struct {
	SavedViewID int64 `json:"saved_view_id" jsonschema:"Numeric ID of the saved view to delete,required"`
}

DeleteInput identifies the saved view to delete.

type Filters 

type Filters struct {
	AssigneeUsernames          []string            `json:"assignee_usernames,omitempty"            jsonschema:"Usernames of the assignees to match"`
	AssigneeWildcardID         string              `json:"assignee_wildcard_id,omitempty"          jsonschema:"Assignee wildcard filter: ANY, ME, or NONE"`
	AuthorUsername             string              `json:"author_username,omitempty"               jsonschema:"Username of the work item author"`
	ClosedAfter                string              `` /* 142-byte string literal not displayed */
	ClosedBefore               string              `` /* 143-byte string literal not displayed */
	Confidential               *bool               `` /* 134-byte string literal not displayed */
	CreatedAfter               string              `json:"created_after,omitempty"                 jsonschema:"Match work items created after this timestamp (ISO 8601)"`
	CreatedBefore              string              `json:"created_before,omitempty"                jsonschema:"Match work items created before this timestamp (ISO 8601)"`
	CRMContactID               string              `json:"crm_contact_id,omitempty"                jsonschema:"CRM contact global ID whose work items to match"`
	CRMOrganizationID          string              `json:"crm_organization_id,omitempty"           jsonschema:"CRM organization global ID whose work items to match"`
	CustomField                []CustomFieldFilter `` /* 141-byte string literal not displayed */
	DueAfter                   string              `json:"due_after,omitempty"                     jsonschema:"Match work items due after this timestamp (ISO 8601)"`
	DueBefore                  string              `json:"due_before,omitempty"                    jsonschema:"Match work items due before this timestamp (ISO 8601)"`
	ExcludeGroupWorkItems      *bool               `json:"exclude_group_work_items,omitempty"      jsonschema:"Exclude work items owned by the group itself"`
	ExcludeProjects            *bool               `json:"exclude_projects,omitempty"              jsonschema:"Exclude work items owned by projects under the namespace"`
	FullPath                   string              `json:"full_path,omitempty"                     jsonschema:"Full path of the project or group whose work items to match"`
	HealthStatusFilter         string              `` /* 145-byte string literal not displayed */
	HierarchyFilters           *HierarchyFilter    `json:"hierarchy_filters,omitempty"             jsonschema:"Filter by position in the work item hierarchy"`
	IID                        string              `json:"iid,omitempty"                           jsonschema:"Internal ID (IID) of a single work item to match"`
	In                         []string            `` /* 128-byte string literal not displayed */
	IncludeDescendantWorkItems *bool               `json:"include_descendant_work_items,omitempty" jsonschema:"Include work items below the matched ones in the hierarchy"`
	IncludeDescendants         *bool               `json:"include_descendants,omitempty"           jsonschema:"Include work items from descendant namespaces"`
	IterationCadenceID         []string            `json:"iteration_cadence_id,omitempty"          tier:"premium" jsonschema:"Iteration cadence global IDs to match"`
	IterationID                []string            `json:"iteration_id,omitempty"                  tier:"premium" jsonschema:"Iteration global IDs to match"`
	IterationWildcardID        string              `json:"iteration_wildcard_id,omitempty"         tier:"premium" jsonschema:"Iteration wildcard filter: NONE, ANY, CURRENT"`
	LabelName                  []string            `json:"label_name,omitempty"                    jsonschema:"Label names to match"`
	MilestoneTitle             []string            `json:"milestone_title,omitempty"               jsonschema:"Milestone titles to match"`
	MilestoneWildcardID        string              `json:"milestone_wildcard_id,omitempty"         jsonschema:"Milestone wildcard filter: NONE, ANY, STARTED, UPCOMING"`
	MyReactionEmoji            string              `json:"my_reaction_emoji,omitempty"             jsonschema:"Emoji the authenticated user reacted with"`
	Not                        *NegatedFilters     `json:"not,omitempty"                           jsonschema:"Values that exclude a work item from the view"`
	Or                         *UnionedFilters     `json:"or,omitempty"                            jsonschema:"Values where matching any one of them includes the work item"`
	ReleaseTag                 []string            `json:"release_tag,omitempty"                   jsonschema:"Release tags to match"`
	ReleaseTagWildcardID       string              `json:"release_tag_wildcard_id,omitempty"       jsonschema:"Release tag wildcard filter: NONE or ANY"`
	Search                     string              `json:"search,omitempty"                        jsonschema:"Free-text search term"`
	State                      string              `json:"state,omitempty"                         jsonschema:"Work item state: opened, closed, locked, or all"`
	Status                     *StatusFilter       `json:"status,omitempty"                        tier:"premium" jsonschema:"Filter by the work item status widget value"`
	Subscribed                 string              `` /* 152-byte string literal not displayed */
	Types                      []string            `json:"types,omitempty"                         jsonschema:"Work item type names to match, e.g. ISSUE, TASK, EPIC"`
	UpdatedAfter               string              `json:"updated_after,omitempty"                 jsonschema:"Match work items updated after this timestamp (ISO 8601)"`
	UpdatedBefore              string              `json:"updated_before,omitempty"                jsonschema:"Match work items updated before this timestamp (ISO 8601)"`
	Weight                     string              `json:"weight,omitempty"                        tier:"premium" jsonschema:"Weight to match"`
	WeightWildcardID           string              `json:"weight_wildcard_id,omitempty"            tier:"premium" jsonschema:"Weight wildcard filter: NONE or ANY"`
	WorkItemTypeIDs            []string            `json:"work_item_type_ids,omitempty"            jsonschema:"Work item type global IDs to match"`
}

Filters mirrors gl.WorkItemSavedViewFilters, the WorkItemSavedViewFilterInput GraphQL input a saved view stores.

Optional scalars are plain strings rather than pointers: the GraphQL input omits empty values, so "" and "field absent" mean the same thing to the server. Booleans stay pointers, because false and absent do not.

The tier tags name the same tiers internal/tools/workitems puts on the filters of the same name, so one filter is advertised at one tier whichever domain a caller reaches it through: iterations, weight, custom fields and status are Premium and health status is Ultimate. A saved view is itself available on every tier; only these conditions inside one are gated. GitLab documents work item status and custom fields at "Tier: Premium, Ultimate" (https://docs.gitlab.com/user/work_items/status/ and https://docs.gitlab.com/user/work_items/custom_fields/), both read on 2026-09-07.

GitLab API docs: https://docs.gitlab.com/api/graphql/reference/#workitemsavedviewfilterinput

type GetInput 

type GetInput struct {
	NamespacePath string `` /* 142-byte string literal not displayed */
	SavedViewID   int64  `json:"saved_view_id"  jsonschema:"Numeric ID of the saved view,required"`
}

GetInput identifies one saved view under a namespace.

type GetOutput 

type GetOutput struct {
	toolutil.HintableOutput
	NamespacePath string `json:"namespace_path"`
	SavedView     Item   `json:"saved_view"`
}

GetOutput carries one saved view, including its filters.

func Get 

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

Get returns one saved view under a namespace, filters included.

type HierarchyFilter 

type HierarchyFilter struct {
	ParentIDs                  []string `json:"parent_ids,omitempty"                    jsonschema:"Parent work item global IDs"`
	IncludeDescendantWorkItems *bool    `json:"include_descendant_work_items,omitempty" jsonschema:"Include work items below the matched parents"`
	ParentWildcardID           string   `json:"parent_wildcard_id,omitempty"            jsonschema:"Parent wildcard filter: NONE or ANY"`
}

HierarchyFilter mirrors gl.WorkItemHierarchyFilter, which filters work items by their position in the work item hierarchy.

GitLab API docs: https://docs.gitlab.com/api/graphql/reference/#hierarchyfilterinput

type Item 

type Item struct {
	ID              int64  `json:"id"                         jsonschema:"Numeric ID of the saved view"`
	GID             string `json:"gid,omitempty"              jsonschema:"GraphQL global ID of the saved view"`
	Name            string `json:"name"                       jsonschema:"Name of the saved view"`
	Description     string `json:"description,omitempty"      jsonschema:"Description of the saved view"`
	IsPrivate       bool   `json:"is_private"                 jsonschema:"Whether the view is private to the user who created it"`
	Subscribed      bool   `json:"subscribed"                 jsonschema:"Whether the authenticated user is subscribed to the view"`
	Filters         any    `` /* 187-byte string literal not displayed */
	Sort            string `json:"sort,omitempty"             jsonschema:"Sort order the view applies"`
	DisplaySettings any    `json:"display_settings,omitempty" jsonschema:"Display settings the consuming UI renders the view with"`
}

Item is one work item saved view. It mirrors gl.WorkItemSavedView.

type ListInput 

type ListInput struct {
	NamespacePath string `json:"namespace_path" jsonschema:"Full path of the group or project whose saved views to list,required"`
	toolutil.GraphQLCursorPaginationInput
}

ListInput selects a page of the saved views under a namespace.

type ListOutput 

type ListOutput struct {
	toolutil.HintableOutput
	NamespacePath string                           `json:"namespace_path"`
	SavedViews    []Item                           `json:"saved_views"`
	Pagination    toolutil.GraphQLPaginationOutput `json:"pagination"`
}

ListOutput carries a page of saved views plus its cursor metadata.

func List 

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

List returns a page of the saved views under a namespace.

Filters are absent from every entry: GitLab resolves that field at most once per GraphQL request, so the SDK's list query does not ask for it. Reading a view's filters means calling Get on it.

type MutateOutput 

type MutateOutput struct {
	toolutil.HintableOutput
	Status    string `json:"status"`
	Message   string `json:"message"`
	SavedView Item   `json:"saved_view"`
}

MutateOutput confirms a saved view mutation and returns the resulting view.

func Create 

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

Create creates a saved view under a namespace.

func Subscribe 

func Subscribe(ctx context.Context, client *gitlabclient.Client, input SubscribeInput) (MutateOutput, error)

Subscribe subscribes the authenticated user to a saved view.

func Unsubscribe 

func Unsubscribe(ctx context.Context, client *gitlabclient.Client, input UnsubscribeInput) (MutateOutput, error)

Unsubscribe removes the authenticated user's subscription to a saved view.

func Update 

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

Update changes the supplied fields of an existing saved view.

type NegatedFilters 

type NegatedFilters struct {
	AssigneeUsernames   []string            `json:"assignee_usernames,omitempty"    jsonschema:"Assignee usernames to exclude"`
	AuthorUsername      []string            `json:"author_username,omitempty"       jsonschema:"Author usernames to exclude"`
	CustomField         []CustomFieldFilter `json:"custom_field,omitempty"          tier:"premium" jsonschema:"Custom field values to exclude"`
	HealthStatusFilter  []string            `json:"health_status_filter,omitempty"  tier:"ultimate" jsonschema:"Health statuses to exclude"`
	IterationID         []string            `json:"iteration_id,omitempty"          tier:"premium" jsonschema:"Iteration global IDs to exclude"`
	IterationWildcardID string              `json:"iteration_wildcard_id,omitempty" tier:"premium" jsonschema:"Iteration wildcard filter to exclude"`
	LabelName           []string            `json:"label_name,omitempty"            jsonschema:"Label names to exclude"`
	MilestoneTitle      []string            `json:"milestone_title,omitempty"       jsonschema:"Milestone titles to exclude"`
	MilestoneWildcardID string              `json:"milestone_wildcard_id,omitempty" jsonschema:"Milestone wildcard filter to exclude"`
	MyReactionEmoji     string              `json:"my_reaction_emoji,omitempty"     jsonschema:"Emoji reaction to exclude"`
	ParentIDs           []string            `json:"parent_ids,omitempty"            jsonschema:"Parent work item global IDs to exclude"`
	ReleaseTag          []string            `json:"release_tag,omitempty"           jsonschema:"Release tags to exclude"`
	Types               []string            `json:"types,omitempty"                 jsonschema:"Work item type names to exclude"`
	Weight              string              `json:"weight,omitempty"                tier:"premium" jsonschema:"Weight to exclude"`
	WorkItemTypeIDs     []string            `json:"work_item_type_ids,omitempty"    jsonschema:"Work item type global IDs to exclude"`
}

NegatedFilters mirrors gl.WorkItemSavedViewNegatedFilters, the "not" sub-filter: a work item matching any of these values is excluded.

GitLab API docs: https://docs.gitlab.com/api/graphql/reference/#workitemsavedviewnegatedfilterinput

type StatusFilter 

type StatusFilter struct {
	ID   string `json:"id,omitempty"   jsonschema:"Status global ID"`
	Name string `json:"name,omitempty" jsonschema:"Status name, e.g. To do or In progress"`
}

StatusFilter mirrors gl.WorkItemStatusFilter, which filters work items by their status widget value. Supply the status ID or its name, not both.

GitLab API docs: https://docs.gitlab.com/api/graphql/reference/#workitemwidgetstatusfilterinput

type SubscribeInput 

type SubscribeInput struct {
	SavedViewID int64 `json:"saved_view_id" jsonschema:"Numeric ID of the saved view to subscribe to,required"`
}

SubscribeInput identifies the saved view to subscribe the caller to.

type UnionedFilters 

type UnionedFilters struct {
	AssigneeUsernames []string            `json:"assignee_usernames,omitempty" jsonschema:"Assignee usernames where matching any one includes the work item"`
	AuthorUsernames   []string            `json:"author_usernames,omitempty"   jsonschema:"Author usernames where matching any one includes the work item"`
	CustomField       []CustomFieldFilter `` /* 129-byte string literal not displayed */
	LabelNames        []string            `json:"label_names,omitempty"        jsonschema:"Label names where matching any one includes the work item"`
}

UnionedFilters mirrors gl.WorkItemSavedViewUnionedFilters, the "or" sub-filter: a work item matching any of these values is included.

GitLab API docs: https://docs.gitlab.com/api/graphql/reference/#workitemsavedviewunionedfilterinput

type UnsubscribeInput 

type UnsubscribeInput struct {
	SavedViewID int64 `json:"saved_view_id" jsonschema:"Numeric ID of the saved view to unsubscribe from,required"`
}

UnsubscribeInput identifies the saved view to unsubscribe the caller from.

type UpdateInput 

type UpdateInput struct {
	SavedViewID     int64          `json:"saved_view_id"              jsonschema:"Numeric ID of the saved view to update,required"`
	Name            string         `json:"name,omitempty"             jsonschema:"New name for the saved view"`
	Description     string         `json:"description,omitempty"      jsonschema:"New description for the saved view"`
	IsPrivate       *bool          `json:"is_private,omitempty"       jsonschema:"Whether the view is private to the user who created it"`
	Filters         *Filters       `json:"filters,omitempty"          jsonschema:"Replacement filters. Omit to leave the existing filters unchanged"`
	Sort            string         `json:"sort,omitempty"             jsonschema:"New sort order, a WorkItemSort enum value such as CREATED_DESC or TITLE_ASC"`
	DisplaySettings map[string]any `` /* 260-byte string literal not displayed */
}

UpdateInput holds the fields to change on an existing saved view. It mirrors gl.UpdateWorkItemSavedViewOptions: every field is optional, and an omitted one is left as it is.

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.