Work item discussion

Overview

Every work item carries a discussion: a list of comments, each of which can be a thread with replies underneath it. You use it to ask the question that unblocks the work, to record the decision that was made, and to mark a thread finished once it has been answered so nobody re-reads it. Reactions let a team agree without adding a comment nobody needed, and @-mentioning somebody puts the item in their attention inbox.

The same discussion is readable from the web app, the CLI and the API, which is what makes it useful to a bot: a pipeline that fails can say so on the item that asked for the change, and a script can sweep the threads nobody resolved.

Before you start

How it works

Threading is one level deep

A discussion is a list of threads. Each thread has one root comment and any number of replies under it, and a reply cannot itself have replies. That is a deliberate ceiling: a two-level tree is a conversation, and a deeper one is an argument nobody can read in order.

A reply is created by naming the root comment it belongs to. Naming a reply instead is refused rather than flattened, so a thread never quietly loses its shape.

Four ways to read the same discussion

They answer different questions, and picking the wrong one is the most common surprise on this page — a plain comment listing returns thread starters only, so replies appear to be missing when they are simply somewhere else.

The discussions listing returns the discussion whole and takes no cursor, so it is the right call for rendering an item and the wrong one for sweeping an item with thousands of comments. The other three are cursor-paged: each answers with a next_token when there is another page, and you hand that back to get it.

Resolution is a property of the thread

Resolving marks the root comment resolved, and with it the thread. Replies cannot be resolved on their own — half a resolved thread would mean the conversation had two answers. Resolving something already resolved is refused rather than treated as a no-op, and so is reopening something that was never resolved, so a script that loops over threads cannot report success for work it did not do.

Resolution is a flag, not a deletion: a resolved thread stays in the discussion, keeps its replies, and can be reopened by anyone with Reporter access. Both transitions land on the item's timeline.

The discussion belongs to the item, not to its number

A work item can be moved into another repository, and when it moves it is renumbered. Its comments, threads, reactions and timeline travel with it — they are attached to the item itself, not to the address you reached it by. The old number stops answering, which is the point: a comment that has moved into a private repository must not stay readable at the number it used to have.

Work items on a group

An item filed on a group rather than on a repository — an epic, or an incident that spans more than one repository — has exactly the same discussion, reached through the group instead of a repository. Every operation on this page exists twice for that reason, once under a repository and once under a group, with identical behaviour, identical scopes and identical errors: the address swaps /repositories/{repo_id} for /groups/{group_id} and nothing else changes. Pick the one that matches where the item lives.

A work item has no diff

A comment on a merge request can pin itself to a line of a file. A work item is not a change, so it has no diff to pin to, and asking for a line-anchored comment on one is refused rather than stored with an empty anchor. Every comment on a work item is a plain comment. If you want the item to point at a specific place in the code, that is a code anchor, which lives on the code links page.

How to

Read a work item's discussion

The whole discussion in one call: every thread, each with its root and its replies in the order they were written, threads ordered by when they were started. Each comment carries its author, when it was written, whether it has been edited, how many replies it has, and its reactions with a flag saying which ones you placed yourself.

List the thread starters

Use this when you want to page through a long discussion, or to find the threads nobody has resolved. It returns root comments only — the replies live behind each root.

Add resolved=false to get the open threads and resolved=true to get the finished ones. Leaving it off returns both.

Read one thread's replies

Ask for the replies by naming the thread's root comment. Naming a reply is refused, because a reply has no replies of its own to list.

Read a single comment

One comment, with its author, its edit flag and its reactions. Useful when you already hold a comment's id — from an earlier listing, or from the commented entry on the item's timeline — and want the current state of that one comment rather than the whole discussion.

Comment on a work item

A comment needs a body and nothing else. To make it a reply instead of a new thread, name the root comment it belongs to.

The body is markdown, between 1 and 10,000 characters after trimming. Leading and trailing whitespace is removed before it is stored, so a comment made entirely of spaces is an empty comment and is refused.

Who hears about it. A comment puts the item in the attention inbox of whoever filed it and of everybody assigned to it, whether or not you name them — so you do not have to @ the person who reported a bug to reach them. You are never raised against your own comment, and closing the item clears both those items and the mentions, so a finished item stops nagging.

Mentioning people. Writing @username in the body puts the item in that person's attention inbox as well, and their name is resolved at the moment you post — so an @ that names nobody quietly resolves to nobody rather than failing the comment. At most 25 distinct people are notified per comment, in the order they first appear. Three things reach nobody: an @ in a place the platform does not read names — inside a code span, a fenced or indented code block, a markdown heading, or a URL — which is what keeps an email address in a stack trace from paging a stranger; your own name, because you are never raised against your own comment; and a name an /assign or /unassign in the same body already claimed, so /assign @sam reaches Sam neither as an assignment nor as a mention. Write the name in an ordinary sentence.

A closed work item still takes comments. The post-mortem on a finished incident is usually the discussion that matters most, so closing an item does not close its discussion.

Reply in a thread

A reply is the same call as a comment with one field added: the id of the thread's root comment. It joins the end of that thread rather than starting a new one, and it raises the same attention items and resolves the same mentions as any other comment.

A reply cannot carry a parent that is itself a reply, and it cannot be resolved on its own — resolution belongs to the thread. If you do not have the root's id to hand, every reply carries the id of the thread it belongs to, so any comment in the thread will tell you.

Comment on a group-scoped work item

Identical in every respect, addressed through the group rather than a repository. Use it for items that span several repositories.

Edit a comment

Editing replaces the body and marks the comment edited; the flag is permanent and visible to everyone, so a silently rewritten argument is not a thing that can happen here. The comment's position in the thread, its replies and its reactions are untouched.

You can always edit your own comment with Reporter access. Editing somebody else's needs Maintainer.

Delete a comment

You can always delete your own comment with Reporter access. Deleting somebody else's needs Maintainer.

Deleting does not leave a tombstone in the discussion — the comment is gone rather than greyed out. The item's timeline keeps the entry recording that the comment was posted, so the fact of the conversation survives even when its text does not.

Resolve a thread

Mark a thread answered so the next reader knows not to reopen the question. Any member at Reporter or above can resolve a thread, not only its author — the person who got the answer is often not the person who asked.

Name the thread's root comment. Resolving a reply, or resolving a thread that is already resolved, is refused.

Reopen a resolved thread

The answer was wrong, or the question came back. Reopening restores the thread to the open list and clears the record of who resolved it.

React to a comment

Eight reactions are available: thumbs_up, thumbs_down, laugh, hooray, confused, heart, rocket and eyes. Anything else is refused, which keeps a discussion's reactions countable and sortable rather than a free-text field.

Each person may place each reaction on each comment once. Placing one you have already placed changes nothing and is not an error, so a retrying script does not double-count. The call answers with the comment's full reaction summary — each reaction, how many people placed it, who they are, and whether you are one of them.

Withdraw a reaction

Removes only your reaction of that kind. Withdrawing one you never placed answers 404 rather than pretending, so a script can tell the difference between "removed it" and "there was nothing there".

See who reacted

The full summary for one comment: every reaction placed on it, the count for each, who placed it, and whether you are one of them. The listings that return comments already attach the same summary to each one, so reach for the dedicated call when you have a comment id and want nothing else.

Follow a work item's timeline

The timeline is everything that has happened to the item in one stream, newest first — comments and thread transitions alongside status changes, assignments, moves, links to commits and merge requests, and criteria passing or regressing. Each entry names its actor and when it happened.

The timeline is a record rather than a view: an entry keeps the scope and number the item had at the time, so moving an item does not rewrite its history into a place it never was. It is read with issue_comment:read, the same scope as the discussion.

Reference

Every operation exists twice — once addressed through a repository, once through a group — with the same behaviour on both.

Reading a discussion

Writing

Thread resolution

Reactions

Timeline

Limits

Two caps apply here, and both are per-plan: one on the comments a work item can carry, one on the reactions a single comment can carry. They bite on posting a comment and on placing a reaction, on a repository item and a group item alike; everything else on this page is uncapped. A capped request is refused with 429 TOO_MANY_REQUESTS and nothing is written — no partial comment and no half-placed reaction.

Replies count. The comment cap is the total number of comments on the item, threads and replies together, not the number of threads. Deleting brings an item back under its ceiling, and deleting a thread root takes the whole thread out at once, so pruning is the way back from a wall of comments.

The reaction cap is per comment across everybody, not per person: it is the number of reactions the comment carries in total. A comment that a hundred people have given a thumbs-up is at the Free ceiling.

Three more bounds apply regardless of plan, because they are shapes rather than allowances:

Raising a cap. Plan limits are a starting point, not a ceiling. An Owner can ask for a single limit to be raised for the namespace without changing plan; moving to a higher plan raises every limit at once. Both are on the billing and plans page.

Troubleshooting

FAQ

Related