Diátaxis type: Reference Domain: Issues Individual tools: 56 Meta-tool:
gitlab_issue(GITLAB_MCP_TOOL_SURFACE=metacatalog) Dynamic IDs:issue.*(default surface, viagitlab_execute_action) GitLab API: Issues API Audience: 👤 End users, AI assistant users
The issues domain covers the full lifecycle of GitLab issues: creation, retrieval, listing, updating, deletion, reordering, moving between projects, subscriptions, to-do creation, time tracking, participants, related merge requests, notes (comments), issue links, discussion threads, issue statistics, work items, and work item saved views.
On the default dynamic surface, these operations are the issue.* entries of the canonical action catalog: find them with gitlab_find_action and run them with gitlab_execute_action by domain.action ID. With GITLAB_MCP_TOOL_SURFACE=individual, each is the tool named in the tables below.
With GITLAB_MCP_TOOL_SURFACE=meta, the whole domain is one gitlab_issue meta-tool that dispatches by action parameter — notes, links, work items, work item saved views, award emoji, resource events, discussions and statistics included. There is no separate discussion or statistics meta-tool; those are actions on gitlab_issue (discussion_list, statistics_get).
"List open issues in project 42" "Create an issue about the login bug" "Close issue #10 in my-project" "What issues are assigned to me?"
| Annotation | ReadOnly | Destructive | Idempotent | Description |
|---|---|---|---|---|
| Read | Yes | No | Yes | Safe read-only operation |
| Create | — | No | — | Creates a new resource |
| Update | — | No | Yes | Modifies an existing resource |
| Delete | — | Yes | Yes | Destroys a resource; protected by confirmation |
Tools marked Delete require user confirmation before execution.
Create a new issue in a GitLab project. Supports title, description (Markdown), assignees, labels, milestone, due date, confidential flag, issue_type (issue/incident/test_case/task), weight, and epic_id. Returns the created issue with ID, IID, state, and web URL.
| Annotation | Create |
|---|
Retrieve a single GitLab issue by its project-scoped IID. Returns title, description, state, labels, assignees, milestone, author, timestamps, and web URL.
| Annotation | Read |
|---|
List issues for a GitLab project with filters for state, labels, milestone, assignee, author, and search. Returns paginated results with issue details.
| Annotation | Read |
|---|
Update a GitLab issue. Supports changing title, description, state (close/reopen), assignees, labels (replace, add, or remove), milestone, due date, confidential flag, issue_type, weight, and discussion_locked. Only specified fields are modified.
| Annotation | Update |
|---|
Permanently delete a GitLab issue. This action cannot be undone. Requires at least Maintainer access level.
| Annotation | Delete |
|---|
Destructive: Protected by confirmation prompt. Permanent deletion cannot be undone.
List issues visible to the authenticated user across all projects (global scope). Supports filtering by state, labels, milestone, scope, search, assignee, author, time range, confidential flag, and ordering. Returns paginated results.
| Annotation | Read |
|---|
Retrieve a single GitLab issue by its global numeric ID (not the project-scoped IID). Useful when you have the global issue ID from another API response.
| Annotation | Read |
|---|
Reorder an issue by specifying the issue to position it before or after. Use move_after_id and/or move_before_id to set the relative position.
| Annotation | Update |
|---|
Move an issue from one project to another. Requires at least Reporter access on both the source and target projects.
| Annotation | Update |
|---|
Subscribe the authenticated user to an issue to receive notifications on updates.
| Annotation | Update |
|---|
Unsubscribe the authenticated user from an issue to stop receiving notifications.
| Annotation | Update |
|---|
Create a to-do item for the authenticated user on the specified issue. The to-do will appear in the user's GitLab to-do list.
| Annotation | Create |
|---|
Set the time estimate for an issue using a human-readable duration (e.g. 3h30m, 1w2d).
| Annotation | Update |
|---|
Reset the time estimate for an issue back to zero.
| Annotation | Update |
|---|
Add spent time to an issue using a human-readable duration (e.g. 1h, 30m) with an optional summary.
| Annotation | Update |
|---|
Reset the total spent time for an issue to zero.
| Annotation | Update |
|---|
Get time tracking statistics for an issue (estimate and spent time).
| Annotation | Read |
|---|
List all participants (users who engaged) in an issue. Returns usernames, names, and profile URLs.
| Annotation | Read |
|---|
List merge requests that will close this issue when merged. Returns MR details including source/target branches.
| Annotation | Read |
|---|
List merge requests related to this issue. Returns MR details including source/target branches.
| Annotation | Read |
|---|
Add a comment (note) to a GitLab issue. Supports Markdown formatting and optional internal visibility flag (visible only to project members).
| Annotation | Create |
|---|
List all comments (notes) on a GitLab issue. Supports ordering by created_at or updated_at, sort direction, and pagination. Returns note body, author, timestamps, and system/internal flags.
| Annotation | Read |
|---|
Get a single comment (note) from a GitLab issue by its note ID, including author, timestamps, body, and internal/system flags.
| Annotation | Read |
|---|
Edit the body text of an existing comment on a GitLab issue. Only the note author or a project maintainer can update a note.
| Annotation | Update |
|---|
Permanently delete a comment from a GitLab issue. Only the note author or a project maintainer can delete a note.
| Annotation | Delete |
|---|
Destructive: Protected by confirmation prompt.
List issue relations (linked issues) for a given issue in a GitLab project. Returns related issues with link type (relates_to, blocks, is_blocked_by).
| Annotation | Read |
|---|
Get a specific issue link by ID, returning source and target issue details with link type.
| Annotation | Read |
|---|
Create a link between two issues. Specify source project/issue and target project/issue. Link types: relates_to (default), blocks, is_blocked_by.
| Annotation | Create |
|---|
Delete an issue link, removing the two-way relationship between the linked issues. This action cannot be undone.
| Annotation | Delete |
|---|
Destructive: Protected by confirmation prompt.
List discussion threads on a project issue.
| Annotation | Read |
|---|
Get a single discussion thread on a project issue.
| Annotation | Read |
|---|
Create a new discussion thread on a project issue.
| Annotation | Create |
|---|
Add a reply note to an existing issue discussion thread.
| Annotation | Create |
|---|
Update an existing note in an issue discussion thread.
| Annotation | Update |
|---|
Delete a note from an issue discussion thread.
| Annotation | Delete |
|---|
Destructive: Protected by confirmation prompt.
Get global issue statistics (counts of all/opened/closed issues).
| Annotation | Read |
|---|
Get issue statistics for a group.
| Annotation | Read |
|---|
Get issue statistics for a project.
| Annotation | Read |
|---|
Iterations are time-boxed sprints (Premium). Iteration events record when an issue's iteration was assigned or removed and when its weight was set.
List iterations (sprints) for a group (Premium). Supports filtering by state (opened, upcoming, current, closed, all), include_ancestors, and search (title). Returns iterations with sequence, title, description, state, start and due dates, web URL, and pagination metadata.
| Annotation | Read |
|---|
List iterations (sprints) for a project (Premium). Supports filtering by state, include_ancestors (pulls in ancestor-group iterations), and search (title). Returns iterations with id, iid, sequence, group_id, title, description, state, start/due dates, timestamps, web URL, and pagination metadata.
| Annotation | Read |
|---|
List iteration events for an issue (Premium) — every assignment or removal of an iteration against the issue, with action, iteration, acting user, and pagination metadata. Supports keyset or offset pagination (page, per_page 1–100, pagination, page_token, order_by, sort asc|desc).
| Annotation | Read |
|---|
Get a single iteration event for an issue (Premium) by iteration_event_id. Returns the event with action, the iteration object, and the acting user.
| Annotation | Read |
|---|
List weight events for an issue (Premium) — every weight value set, with the weight, the acting user, and pagination metadata. Supports keyset or offset pagination (page, per_page 1–100, pagination, page_token, order_by, sort asc|desc).
| Annotation | Read |
|---|
Get a single work item by IID. Returns the hierarchy parent and child work items (namespace path and IID) alongside linked items, plus the widget values a work item type carries: milestone_id, iteration_id, weight, health_status, color, start_date and due_date. author and each entry of assignees are whole user objects (id, username, name, state, avatar_url, web_url, created_at) and each entry of labels is a whole label object (id, name, color, description, description_html, text_color), because the GraphQL fragment fetches all of those on every call. The Markdown rendering still prints names. Experimental: the Work Items API may introduce breaking changes between minor versions.
| Annotation | Read |
|---|
List work items for a project or group. Each item includes its author, assignees and labels as whole objects, its linked items and its hierarchy parent and child work items (namespace path and IID), with cursor pagination (first/after forward, last/before backward). The cursor picks the direction: before on its own pages backward at the default size, and naming both first and last is refused, because GitLab refuses it too. sort is a GraphQL WorkItemSort value such as CREATED_DESC (the default), TITLE_ASC or PRIORITY_DESC, not the asc/desc pair the REST endpoints take. On Premium and Ultimate instances each listed item also carries status, weight, health_status, iteration_id and color, which are asked for only there: a Community Edition schema does not define those widgets and one unknown field fails the whole query. Experimental: the Work Items API may introduce breaking changes between minor versions.
The full filter set:
| Parameter | Type | Description |
|---|---|---|
full_path |
string | Project or group namespace. Required |
state |
string | opened, closed or all |
search |
string | Free-text search over title and description |
in |
array | Fields search is matched against: TITLE, DESCRIPTION |
types |
array | IssueType values such as ISSUE, TASK, EPIC |
author_username |
string | Username of the author |
assignee_usernames |
array | Usernames of the assignees |
assignee_wildcard_id |
string | ANY, ME or NONE |
my_reaction_emoji |
string | Emoji the authenticated user reacted with |
subscribed |
string | EXPLICITLY_SUBSCRIBED or EXPLICITLY_UNSUBSCRIBED |
crm_contact_id |
string | CRM contact numeric ID as a string, not a global ID |
crm_organization_id |
string | CRM organization numeric ID as a string, not a global ID |
ids |
array | Work item global IDs (gid://gitlab/WorkItem/123) |
iids |
array | Work item internal IDs, as strings |
parent_ids |
array | Parent work item global IDs. Pairs with include_descendants |
label_name |
array | Label names |
milestone_title |
array | Milestone titles, not the milestone_id create and update take |
milestone_wildcard_id |
string | ANY, NONE, STARTED or UPCOMING |
release_tag |
array | Release tags |
release_tag_wildcard_id |
string | ANY or NONE |
iteration_id |
array | Iteration global IDs. A list of global IDs, unlike the single numeric iteration_id of create and update (Premium) |
iteration_cadence_id |
array | Iteration cadence global IDs (Premium) |
iteration_wildcard_id |
string | ANY, CURRENT or NONE (Premium) |
weight |
string | Weight to match. GitLab types this filter as a string (Premium) |
weight_wildcard_id |
string | ANY or NONE (Premium) |
health_status_filter |
string | onTrack, needsAttention, atRisk, ANY or NONE. Case sensitive (Ultimate) |
closed_after, closed_before |
string | ISO 8601 date-time. A bare date is read as midnight UTC |
created_after, created_before |
string | ISO 8601 date-time. A bare date is read as midnight UTC |
due_after, due_before |
string | ISO 8601 date-time. A bare date is read as midnight UTC |
updated_after, updated_before |
string | ISO 8601 date-time. A bare date is read as midnight UTC |
confidential |
boolean | Only confidential or only non-confidential work items |
include_ancestors, include_descendants |
boolean | Widen the search up or down the namespace hierarchy |
sort |
string | A WorkItemSort value |
returned_fields |
array | Which fields of each item to ask for, not which items match. See below |
first, after, last, before |
int/string | Cursor pagination |
A timestamp none of the three spellings can read stops the call and names the filter it came from, rather than being dropped: a list narrowed by a date the server ignored answers with more work items than were asked for, and nothing in the answer would say so.
returned_fields selects the GraphQL fragment rather than the result set: it decides which fields of each matching work item come back, and no work item is included or excluded by it. Omitting it asks for the default set, which is every Community Edition field plus the five Enterprise ones on a Premium or Ultimate instance; naming a subset such as ["iid", "title"] makes a large page much smaller. The accepted names are assignees, author, closedAt, color, confidential, createdAt, description, healthStatus, hierarchy, id, iid, iteration, labels, linkedItems, milestone, startAndDueDate, state, status, title, type, updatedAt, webUrl and weight. A name outside that set stops the call before anything is sent. The five Enterprise names (color, healthStatus, iteration, status, weight) fail the whole query against a Community Edition instance, whose schema does not define those widgets.
| Annotation | Read |
|---|
Create a new work item. Requires full_path, work_item_type_id, and title. Supports status (TODO/IN_PROGRESS/DONE/WONT_DO/DUPLICATE, Premium) and linked_items to link other work items on creation. status and color are Premium: client-go groups both with weight, iteration and health status as fields the Community Edition schema does not define, and GitLab documents work item status and epics alike at Premium and Ultimate.
Five further parameters: parent_id (numeric ID of the parent work item, which creates the item already under its parent instead of a create followed by an update), iteration_id (numeric ID of the iteration, Premium), crm_contact_ids (CRM contact IDs to attach), created_at (an ISO 8601 date-time recorded instead of now, which GitLab accepts from instance administrators and project owners only, and which is refused here by name when it cannot be read) and create_source (a free-text name of whatever triggered the creation, recorded for tracking and changing nothing about the work item). start_date and due_date are calendar dates in YYYY-MM-DD form, and one that cannot be read stops the call and names the field rather than being dropped, so a work item is never created without a date that was asked for. Experimental: the Work Items API may introduce breaking changes between minor versions.
| Annotation | Create |
|---|
Update an existing work item by IID. Supports changing title, state (CLOSE/REOPEN), description, assignees, milestone, labels (add/remove), dates, weight, health status, iteration, color, and status (TODO/IN_PROGRESS/DONE/WONT_DO/DUPLICATE). color and status are Premium, as they are on create. assignee_ids and crm_contact_ids replace the whole list: an empty array removes every entry, and omitting the field leaves it untouched; removing entries that exist requires confirm=true or an approved confirmation prompt. start_date and due_date are calendar dates in YYYY-MM-DD form, and one that cannot be read stops the call by name before anything is sent. Experimental: the Work Items API may introduce breaking changes between minor versions.
| Annotation | Update |
|---|
Permanently delete a work item by IID. This action cannot be undone. Experimental: the Work Items API may introduce breaking changes between minor versions.
| Annotation | Delete |
|---|
Destructive: Protected by confirmation prompt.
List available work item types (system-defined and custom) for a project or group namespace. Returns type ID, name, and enabled flag. Supports filtering by name and only_available, with cursor pagination (first/after forward, last/before backward). The cursor picks the direction: before on its own pages backward at the default size, and naming both first and last is refused, because GitLab refuses it too. Experimental: the Work Items API may introduce breaking changes between minor versions.
| Annotation | Read |
|---|
A saved view stores a named, reusable work item filter under a group or project namespace: the filter itself, the sort order, and the display settings the consuming UI renders it with. Available on Free, Premium and Ultimate. The GraphQL surface is marked experimental by GitLab and may introduce breaking changes between minor versions.
sort is a WorkItemSort enum value (CREATED_ASC, CREATED_DESC, TITLE_ASC, TITLE_DESC, UPDATED_ASC, UPDATED_DESC, PRIORITY_ASC, WEIGHT_DESC and the rest of the enum). display_settings is an opaque JSON object GitLab validates against its own schema, so its keys are camelCase: viewMode (list, board or table), hiddenMetadataKeys, collapsedGroups, visibleGroups, groupOrder.
filters mirrors GitLab's WorkItemSavedViewFilterInput one for one, including the nested not, or, hierarchy_filters, status and custom_field sub-objects. The eight time filters (created_after, created_before, closed_after, closed_before, due_after, due_before, updated_after, updated_before) take ISO 8601 timestamps.
A saved view is available on every tier, but some of the conditions inside one are not, and each is advertised at the same tier gitlab_list_work_items advertises the filter of the same name: iteration_id, iteration_cadence_id, iteration_wildcard_id, weight, weight_wildcard_id, status and custom_field are Premium, and health_status_filter is Ultimate. The same applies to their counterparts inside not and or.
Get a single saved view by namespace path and numeric ID. This is the only action that returns the view's filters: GitLab resolves that field at most once per GraphQL request, so the list query does not ask for it. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Read |
|---|
List the saved views under a group or project namespace, with cursor pagination (first/after forward, last/before backward). The cursor picks the direction: before on its own pages backward at the default size, and naming both first and last is refused, because GitLab refuses it too. filters is omitted from every entry. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Read |
|---|
Create a saved view under a namespace. Requires namespace_path, name and sort. Optional description, is_private (defaults to true), filters and display_settings; an omitted display_settings is stored as an empty object. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Create |
|---|
Update a saved view by numeric ID. Every field is optional and an omitted one is left unchanged. Supplying filters or display_settings replaces the stored value wholesale, so read the current one with gitlab_work_item_saved_view_get first when the intent is to add a condition rather than replace the query. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Update |
|---|
Permanently delete a saved view by numeric ID. This action cannot be undone and removes the view for everyone it was shared with. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Delete |
|---|
Destructive: Protected by confirmation prompt.
Subscribe the authenticated user to a saved view, so it appears among their followed views. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Update |
|---|
Unsubscribe the authenticated user from a saved view. The view itself is untouched. Experimental: the Work Item Saved Views API may introduce breaking changes between minor versions.
| Annotation | Update |
|---|
| # | Tool Name | Category | Annotation |
|---|---|---|---|
| 1 | gitlab_issue_create |
Core CRUD | Create |
| 2 | gitlab_issue_get |
Core CRUD | Read |
| 3 | gitlab_issue_list |
Core CRUD | Read |
| 4 | gitlab_issue_update |
Core CRUD | Update |
| 5 | gitlab_issue_delete |
Core CRUD | Delete |
| 6 | gitlab_issue_list_all |
Query & Navigation | Read |
| 7 | gitlab_issue_get_by_id |
Query & Navigation | Read |
| 8 | gitlab_issue_reorder |
Actions | Update |
| 9 | gitlab_issue_move |
Actions | Update |
| 10 | gitlab_issue_subscribe |
Actions | Update |
| 11 | gitlab_issue_unsubscribe |
Actions | Update |
| 12 | gitlab_issue_create_todo |
Actions | Create |
| 13 | gitlab_issue_time_estimate_set |
Time Tracking | Update |
| 14 | gitlab_issue_time_estimate_reset |
Time Tracking | Update |
| 15 | gitlab_issue_spent_time_add |
Time Tracking | Update |
| 16 | gitlab_issue_spent_time_reset |
Time Tracking | Update |
| 17 | gitlab_issue_time_stats_get |
Time Tracking | Read |
| 18 | gitlab_issue_participants |
Relationships | Read |
| 19 | gitlab_issue_mrs_closing |
Relationships | Read |
| 20 | gitlab_issue_mrs_related |
Relationships | Read |
| 21 | gitlab_issue_note_create |
Notes | Create |
| 22 | gitlab_issue_note_list |
Notes | Read |
| 23 | gitlab_issue_note_get |
Notes | Read |
| 24 | gitlab_issue_note_update |
Notes | Update |
| 25 | gitlab_issue_note_delete |
Notes | Delete |
| 26 | gitlab_issue_link_list |
Issue Links | Read |
| 27 | gitlab_issue_link_get |
Issue Links | Read |
| 28 | gitlab_issue_link_create |
Issue Links | Create |
| 29 | gitlab_issue_link_delete |
Issue Links | Delete |
| 30 | gitlab_list_issue_discussions |
Discussions | Read |
| 31 | gitlab_get_issue_discussion |
Discussions | Read |
| 32 | gitlab_create_issue_discussion |
Discussions | Create |
| 33 | gitlab_add_issue_discussion_note |
Discussions | Create |
| 34 | gitlab_update_issue_discussion_note |
Discussions | Update |
| 35 | gitlab_delete_issue_discussion_note |
Discussions | Delete |
| 36 | gitlab_get_issue_statistics |
Statistics | Read |
| 37 | gitlab_get_group_issue_statistics |
Statistics | Read |
| 38 | gitlab_get_project_issue_statistics |
Statistics | Read |
| 39 | gitlab_list_group_iterations |
Iterations (Premium) | Read |
| 40 | gitlab_list_project_iterations |
Iterations (Premium) | Read |
| 41 | gitlab_issue_iteration_event_list |
Iterations (Premium) | Read |
| 42 | gitlab_issue_iteration_event_get |
Iterations (Premium) | Read |
| 43 | gitlab_issue_weight_event_list |
Iterations (Premium) | Read |
| 44 | gitlab_get_work_item |
Work Items | Read |
| 45 | gitlab_list_work_items |
Work Items | Read |
| 46 | gitlab_create_work_item |
Work Items | Create |
| 47 | gitlab_update_work_item |
Work Items | Update |
| 48 | gitlab_delete_work_item |
Work Items | Delete |
| 49 | gitlab_list_work_item_types |
Work Items | Read |
| 50 | gitlab_work_item_saved_view_get |
Work Item Saved Views | Read |
| 51 | gitlab_work_item_saved_view_list |
Work Item Saved Views | Read |
| 52 | gitlab_work_item_saved_view_create |
Work Item Saved Views | Create |
| 53 | gitlab_work_item_saved_view_update |
Work Item Saved Views | Update |
| 54 | gitlab_work_item_saved_view_delete |
Work Item Saved Views | Delete |
| 55 | gitlab_work_item_saved_view_subscribe |
Work Item Saved Views | Update |
| 56 | gitlab_work_item_saved_view_unsubscribe |
Work Item Saved Views | Update |
The following tools are annotated with DestructiveHint: true and require user confirmation before execution:
gitlab_issue_delete— permanently deletes an issuegitlab_issue_note_delete— permanently deletes an issue commentgitlab_issue_link_delete— removes the link between two issuesgitlab_delete_issue_discussion_note— deletes a note from a discussion threadgitlab_delete_work_item— permanently deletes a work itemgitlab_work_item_saved_view_deletedeletes a work item saved view permanently