gitlab-org--gitlab-foss/doc/user/discussions/index.md

stage	group	info	type
Create	Code Review	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	reference, howto

Comments and threads (FREE)

GitLab encourages communication through comments, threads, and code suggestions.

Two types of comments are available:

• A standard comment.
• A comment in a thread, which can be resolved.

In a comment, you can enter Markdown and use quick actions.

You can suggest code changes in your commit diff comment, which the user can accept through the user interface.

Places you can add comments

You can create comments in places like:

• Commit diffs
• Commits
• Designs
• Epics
• Issues
• Merge requests
• Snippets

Each object can have as many as 5,000 comments.

Mentions

You can mention a user or a group (including subgroups) in your GitLab instance with @username or @groupname. All mentioned users are notified with to-do items and emails. Users can change this setting for themselves in the notification settings.

You can quickly see which comments involve you, because mentions for yourself (the user currently signed in) are highlighted in a different color.

Avoid mentioning @all in issues and merge requests, because it sends an email notification to all the members of that project's group. This might be interpreted as spam. Notifications and mentions can be disabled in a group's settings.

Mention a group in an issue or merge request

When you mention a group in a comment, every member of the group gets a to-do item added to their To-do list.

1. Open the MR or issue.
2. In a comment, type @ followed by the user, group, or subgroup namespace. For example, @alex, @alex-team, or @alex-team/marketing.
3. Select Comment.

A to-do item is created for all the group and subgroup members.

Add a comment to a merge request diff

You can add comments to a merge request diff. These comments persist, even when you:

• Force-push after a rebase.
• Amend a commit.

To add a commit diff comment:

1. To select a specific commit, on the merge request, select the Commits tab, select the commit message. To view the latest commit, select the Changes tab.
2. By the line you want to comment on, hover over the line number and select Comment ({comment}). You can select multiple lines by dragging the Comment ({comment}) icon.
3. Enter your comment and select Start a review or Add comment now.

The comment is displayed on the merge request's Discussions tab.

The comment is not displayed on your project's Repository > Commits page.

NOTE: When your comment contains a reference to a commit included in the merge request, it's automatically converted to a link in the context of the current merge request. For example, 28719b171a056960dfdc0012b625d0b47b123196 becomes https://gitlab.example.com/example-group/example-project/-/merge_requests/12345/diffs?commit_id=28719b171a056960dfdc0012b625d0b47b123196.

Add a comment to a commit

You can add comments and threads to a particular commit.

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Repository > Commits.
3. Below the commits, in the Comment field, enter a comment.
4. Select Comment or select the down arrow ({chevron-down}) to select Start thread.

WARNING: Threads created this way are lost if the commit ID changes after a force push.

Add a comment to an image

In merge requests and commit detail views, you can add a comment to an image. This comment can also be a thread.

1. Hover your mouse over the image.
2. Select the location where you want to comment.

An icon is displayed on the image and a comment field is displayed.

Reply to a comment by sending email

If you have "reply by email" configured, you can reply to comments by sending an email.

• When you reply to a standard comment, it creates another standard comment.
• When you reply to a threaded comment, it creates a reply in the thread.
• When you send an email to an issue email address, it creates a standard comment.

You can use Markdown and quick actions in your email replies.

Edit a comment

You can edit your own comment at any time. Anyone with at least the Maintainer role can also edit a comment made by someone else.

To edit a comment:

1. On the comment, select Edit comment ({pencil}).
2. Make your edits.
3. Select Save changes.

Editing a comment to add a mention

By default, when you mention a user, GitLab creates a to-do item for them, and sends them a notification email.

If you edit an existing comment to add a user mention that wasn't there before, GitLab:

• Creates a to-do item for the mentioned user.
• Does not send a notification email.

Prevent comments by locking an issue

You can prevent public comments in an issue or merge request. When you do, only project members can add and edit comments.

Prerequisite:

• In merge requests, you must have at least the Developer role.
• In issues, you must have at least the Reporter role.

1. On the right sidebar, next to Lock issue or Lock merge request, select Edit.
2. On the confirmation dialog, select Lock.

Notes are added to the page details.

If an issue or merge request is locked and closed, you cannot reopen it.

Add an internal note

• Introduced in GitLab 13.9 with a flag named confidential_notes. Disabled by default.
• Changed in GitLab 14.10: you can only mark comments in issues and epics as confidential. Previously, it was also possible for comments in merge requests and snippets.
• Renamed from "confidential comments" to "internal notes" in GitLab 15.0.
• Enabled on GitLab.com and self-managed in GitLab 15.0.
• Feature flag confidential_notes removed in GitLab 15.2.

You can add an internal note to an issue or an epic. It's then visible only to the following people:

• Project members who have at least the Reporter role
• Issue or epic author
• Users assigned to the issue or epic

Keep in mind:

• Replies to internal notes are also internal.
• You can not turn an internal note into a regular comment.

Prerequisites:

• You must either:
  • Have at least the Reporter role for the project.
  • Be the issue or epic assignee.
  • Be the issue or epic author.

To add an internal note:

1. Start adding a new comment.
2. Below the comment, select the Make this an internal note checkbox.
3. Select Add internal note.

You can also mark an issue as confidential.

Show only comments

For issues and merge requests with many comments, you can filter the page to show comments only.

1. Open a merge request's Discussion tab, or epic or issue's Overview tab.
2. On the right side of the page, select from the filter:
   • Show all activity: Display all user comments and system notes. (issue updates, mentions from other issues, changes to the description, and so on).
   • Show comments only: Display only user comments.
   • Show history only: Display only activity notes.

GitLab saves your preference, so it persists when you visit the same page again from any device you're logged into.

View description change history (PREMIUM)

Introduced in GitLab 12.6.

You can see changes to the description listed in the history.

To compare the changes, select Compare with previous version.

Change activity sort order

Introduced in GitLab 12.10.

You can reverse the default order and interact with the activity feed sorted by most recent items at the top. Your preference is saved in local storage and automatically applies to every issue, merge request, or epic you view.

To change the activity sort order:

1. Select the Oldest first (or Newest first) dropdown list.
2. Select either oldest or newest items to be shown first.

Assign an issue to the commenting user

Introduced in GitLab 13.1.

You can assign an issue to a user who made a comment.

1. In the comment, select the More Actions ({ellipsis_v}) menu.
2. Select Assign to commenting user:
3. To unassign the commenter, select the button again.

Create a thread by replying to a standard comment

When you reply to a standard comment, you create a thread.

Prerequisites:

• You must have at least the Guest role.
• You must be in an issue, merge request, or epic. Threads in commits and snippets are not supported.

To create a thread by replying to a comment:

1. On the top right of the comment, select Reply to comment ({comment}).

   

   The reply section is displayed.

2. Enter your reply.

3. Select Reply or Add comment now (depending on where in the UI you are replying).

The top comment is converted to a thread.

Create a thread without replying to a comment

You can create a thread without replying to a standard comment.

Prerequisites:

• You must have at least the Guest role.
• You must be in an issue, merge request, commit, or snippet.

To create a thread:

1. Enter a comment.
2. Below the comment, to the right of the Comment button, select the down arrow ({chevron-down}).
3. From the list, select Start thread.
4. Select Start thread again.

A threaded comment is created.

Resolve a thread

Resolving comments individually was removed in GitLab 13.6.

In a merge request, you can resolve a thread when you want to finish a conversation.

Prerequisites:

• You must have at least the Developer role or be the author of the change being reviewed.
• Resolvable threads can be added only to merge requests. It doesn't work for comments in issues, commits, or snippets.

To resolve a thread:

1. Go to the thread.
2. Do one of the following:
   • In the top right of the original comment, select the Resolve thread ({check-circle}) icon.
   • Below the last reply, in the Reply field, select Resolve thread.
   • Below the last reply, in the Reply field, enter text, select the Resolve thread checkbox, and select Add comment now.

At the top of the page, the number of unresolved threads is updated:

Move all unresolved threads in a merge request to an issue

If you have multiple unresolved threads in a merge request, you can create an issue to resolve them separately. In the merge request, at the top of the page, click the ellipsis icon button ({ellipsis_v}) in the threads control and then select Create issue to resolve all threads:

All threads are marked as resolved, and a link is added from the merge request to the newly created issue.

Move one unresolved thread in a merge request to an issue

If you have one specific unresolved thread in a merge request, you can create an issue to resolve it separately. In the merge request, under the last reply to the thread, next to Resolve thread, select Create issue to resolve thread ({issue-new}):

The thread is marked as resolved, and a link is added from the merge request to the newly created issue.

Prevent merge unless all threads are resolved

You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, the Unresolved threads counter in a merge request is shown in orange when at least one thread remains unresolved.

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > Merge requests.
3. In the Merge checks section, select the All threads must be resolved checkbox.
4. Select Save changes.

Automatically resolve threads in a merge request when they become outdated

You can set merge requests to automatically resolve threads when lines are modified with a new push.

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > Merge requests.
3. In the Merge options section, select Automatically resolve merge request diff threads when they become outdated.
4. Select Save changes.

Threads are now resolved if a push makes a diff section outdated. Threads on lines that don't change and top-level resolvable threads are not resolved.

Display paginated merge request discussions

• Introduced in GitLab 15.1 with a flag named paginated_mr_discussions. Disabled by default.
• Enabled on GitLab.com in GitLab 15.2.
• Enabled on self-managed in GitLab 15.3.

FLAG: On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to disable the feature flag named paginated_mr_discussions. On GitLab.com, this feature is available.

A merge request can have many discussions. Loading them all in a single request can be slow. To improve the performance of loading discussions, they are split into multiple pages, loading sequentially.