Review with comments

When you open a merge request, reviewers can discuss it before it is approved. Comment threads attach to a merge request or to a specific block, hold a conversation of messages, and can mention other users.

Start a thread

createCommentThread opens a thread with its first message. Attach it to a merge request, or to a block for an inline note:

const { thread } = await cms.api.pages.createCommentThread({
  body: {
    targetType: 'mergeRequest',
    mergeRequestId: mr.mergeRequestId,
    body: 'The hero copy reads a bit long. @editor-2 thoughts?',
    mentions: ['editor-2'],
  },
});

For a block-level note, use targetType: 'block' with a blockId.

Reply

Add messages to a thread with createCommentMessage (optionally replying to a specific message via parentMessageId):

await cms.api.pages.createCommentMessage({
  body: { threadId: thread.id, body: 'Shortened it, take another look.' },
});

Mentions and notifications

A mentions: [userId] array, on a thread or a message, notifies those users. Mentions, replies, and thread resolution raise notifications in the recipient's inbox; listMentions lists a user's mentions directly.

Resolve

When a discussion is settled, resolve the thread (and reopenCommentThread if it comes back):

await cms.api.pages.resolveCommentThread({ body: { threadId: thread.id } });

Resolved threads drop out of the default listCommentThreads view.