| name | link-work-items |
| description | Create, change, or remove a relationship link between two GitLab work items —
related, blocks, or blocked-by. Use whenever the user wants one ticket marked as
blocking, blocked by, or related to another (e.g. "block api#16 on api#20",
"mark these as related") rather than describing the relationship in prose. |
Link two GitLab work items via the relationship API. Prose like "blocked by #N" is invisible to GitLab's board and "Linked items" widget — the formal link is the source of truth.
linkType is uppercase in both APIs: RELATED | BLOCKS | BLOCKED_BY. Direction is from the source: BLOCKED_BY on source #16 means "#16 is blocked by the target".
Preferred: GitLab MCP
Use mcp__gitlab__manage_work_item with action: add_link. id and targetId both take the numeric work item ID from mcp__gitlab__browse_work_items results. Use action: remove_link to delete a link.
Fallback: glab api graphql
SRC=$(glab api graphql -f query='query { project(fullPath: "PROJECT") { workItems(iid: "SRC_IID") { nodes { id } } } }' | jq -r '.data.project.workItems.nodes[0].id')
TGT=$(glab api graphql -f query='query { project(fullPath: "PROJECT") { workItems(iid: "TGT_IID") { nodes { id } } } }' | jq -r '.data.project.workItems.nodes[0].id')
glab api graphql -f query="mutation { workItemAddLinkedItems(input: { id: \"$SRC\", workItemsIds: [\"$TGT\"], linkType: BLOCKED_BY }) { errors workItem { iid } } }"
glab api graphql -f query="mutation { workItemRemoveLinkedItems(input: { id: \"$SRC\", workItemsIds: [\"$TGT\"] }) { errors workItem { iid } } }"
Gotchas
workItemsIds is plural (max 10 per call) in the GraphQL fallback.
- Neither the MCP nor the GraphQL API can update an existing link type. To change direction, remove and re-add.