Help Center/CodeArts Repo/API Reference/APIs/Review/Creating an MR Review
Updated on 2025-05-15 GMT+08:00
View PDF

Creating an MR Review

Function

This API is used to create an MR review comment.

URI

POST /v2/repositories/{repository_id}/merge_requests/{merge_request_iid}/discussions

Table 1 Path parameters

Parameter

Mandatory

Type

Description

repository_id

Yes

Integer

Explanation:

Repository ID.

Constraints:

Mandatory

Range:

Minimum value: 1

Maximum value: 2147483647

merge_request_iid

Yes

Integer

Explanation:

MR IID (MR sequence number in the repository).

Constraints:

Mandatory

Range:

Minimum value: 1

Maximum value: 2147483647

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Explanation:

User token. It can be obtained by calling the corresponding IAM API. The value of X-Subject-Token in the response header is the user token.

Constraints:

Mandatory

Range:

1–100,000 characters.

Default value:

None

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

body

Yes

String

Explanation:

Review comment.

Constraints:

Mandatory

Range:

Maximum length: 8,000 characters.

Characters: Unicode \u0000 to \uffff. Special characters, such as emojis and uncommon characters, are not supported.

Blank: The value cannot be null, an empty string, or only spaces.

severity

No

String

Explanation:

Severity. Non-suggestion reviews cannot be resolved by the assignee, MR creator, or committer.

Range:

Not passed or not an enumerated value. The default value is suggestion.

  • suggestion
  • minor
  • major
  • fatal

assignee_id

No

String

Explanation:

Assigner ID. The value can be a user ID or username.

Range:

Max. 255 characters.

review_categories

No

String

Explanation:

Review comment type.

Constraints:

Only the configured types can be used. To configure a review type, choose Settings > Policy Settings > Review Comments.

review_modules

No

String

Explanation:

Review comment module.

Constraints:

Only the configured modules can be used. To configure a review type, choose Settings > Policy Settings > Review Comments.

proposer_id

No

String

Explanation:

Reviewer ID. The value can be a user ID or username.

Range:

Max. 255 characters.

position

No

PositionDto object

Explanation:

Code location information to associate the comment with.

Range:

None

lineTypes

No

String

Explanation:

Mode in which the comment is provided.

Range:

  • new: On the right of the file comparison result.
  • old: On the left of the file comparison result.
Table 4 PositionDto

Parameter

Mandatory

Type

Description

base_sha

No

String

Explanation:

Base commit node of the source branch.

Range:

40 digits and letters.

start_sha

No

String

Explanation:

Latest commit node of the target branch.

Range:

40 digits and letters.

head_sha

No

String

Explanation:

Latest commit node of the source branch.

Range:

40 digits and letters.

old_path

No

String

Explanation:

Old file path.

Range:

None

new_path

No

String

Explanation:

New file path.

Range:

None

position_type

No

String

Explanation:

Change type.

Range:

None

Default value:

text

old_line

No

Integer

Explanation:

Line number before change. If the value is less than or equal to 0 or is null, the line is new and displayed in green on the right for comparison.

Range:

–1 to 2147483647 or null

new_line

No

Integer

Explanation:

New line No.

If the value is less than or equal to 0 or is null, the line is deleted and displayed in red on the left for comparison.

Range:

–1 to 2147483647 or null

Response Parameters

Status code: 200

Table 5 Response body parameters

Parameter

Type

Description

error

Error object

Explanation:

Response error code.

result

MergeRequestDiscussionDto object

Explanation:

Review comment information.

Range:

None

status

String

Explanation:

Response status.

Range:

  • success: The API call is successful.
  • failed: The API call failed.
Table 6 Error

Parameter

Type

Description

code

String

Explanation:

Error code returned when the API fails to be called.

Range:

  • CH.10000. The system is busy. Try again later.

message

String

Explanation:

Error message returned when the API fails to be called.

Range:

  • The system is busy. Try again later.
Table 7 MergeRequestDiscussionDto

Parameter

Type

Description

id

String

Explanation:

ID shared by the main comment and reply, which is generally called discussion_id.

Range:

40 digits and letters.

individual_note

Boolean

Explanation:

Whether the comment is individual and does not need resolution by others.

Range:

  • true: Yes
  • false: No

notes

Array of NoteDto objects

Explanation:

Main comment and reply list. The first one is the main comment. (This API is used to create a main comment. Therefore, there is only one comment.)

Range:

None

project_id

Integer

Explanation:

Repository ID.

Range:

Minimum value: 1

Maximum value: 2147483647

noteable_type

String

Explanation:

Comment type.

Range:

  • MergeRequest: Comment for MR (When you select a commit under an MR and add a review comment, the comment is still of the MergeRequest type).
  • Commit: Comment for code or a specific commit.

commit_id

String

Explanation:

Associated commit ID: SHA value of a commit. This field applies when noteable_type is set to Commit.

Range:

40 digits and letters.

project_full_path

String

Explanation:

Repository path.

Range:

None

a_mode

String

Explanation:

Mode of an associated file before the change. If the file is new, the value is 0.

Range:

File permissions supported by Git, for example, 100644, 100755, 120000, and 160000.

b_mode

String

Explanation:

Mode of an associated file after the change. If the file is deleted, the value is 0.

Range:

File permissions supported by Git, for example, 100644, 100755, 120000, and 160000.

deleted_file

Boolean

Explanation:

Whether an associated file is deleted.

Range:

  • true: Yes
  • false or null: No

new_file

Boolean

Explanation:

Whether an associated file is new.

Range:

  • true: Yes
  • false or null: No

resolved

Boolean

Explanation:

Whether the review comment has been resolved.

Range:

  • true: Yes
  • false or null: No

archived

Boolean

Explanation:

Whether the review comment has been archived. Archived comments cannot be edited, deleted, replied, or resolved.

Range:

  • true: Yes
  • false or null: No

review_categories

String

Explanation:

Comment type key.

The values of review_categories, review_categories_cn, and review_categories_en must match.

Range:

None

review_categories_cn

String

Explanation:

Comment type in Chinese.

The values of review_categories and review_categories_cn must match.

Range:

None

review_categories_en

String

Explanation:

Comment type in English.

The values of review_categories and review_categories_en must match.

Range:

None

review_modules

String

Explanation:

Review comment module.

Range:

None

severity

String

Explanation:

Review comment severity key.

Range:

  • suggestion
  • minor
  • major
  • fatal

severity_cn

String

Explanation:

Severity in Chinese.

Range:

  • Suggestion
  • Minor
  • Major
  • Fatal

severity_en

String

Explanation:

Severity in English.

Range:

  • Suggestion
  • Minor
  • Major
  • Fatal

assignee

UserBasicDto object

Explanation:

Assignee details.

Range:

None

proposer

UserBasicDto object

Explanation:

Proposer details.

Range:

None

merge_request_version_params

MergeRequestVersionParamsDto object

Explanation:

MR version details.

Range:

None

diff_file

String

Explanation:

File path change.

Range:

None

added_lines

Integer

Explanation:

Number of new lines.

Range:

Minimum value: 0

Maximum value: 2147483647

removed_lines

Integer

Explanation:

Number of deleted lines.

Range:

Minimum value: 0

Maximum value: 2147483647

Table 8 NoteDto

Parameter

Type

Description

id

Integer

Explanation:

Comment ID, which is not shared by the main comment and replies.

Range:

Minimum value: 1

Maximum value: 2147483647

type

String

Explanation:

Note type.

Range:

  • DiffNote: A comment that needs to be resolved on the file change page.
  • MergeRequestNote: A comment that needs to be resolved on the details page.
  • null: A comment that does not need to be resolved on the details page.

body

String

Explanation:

Review comment content.

Range:

Maximum length: 8,000 characters.

Characters: Unicode \u0000 to \uffff. Special characters, such as emojis and uncommon characters, are not supported.

Blank: The value cannot be null, an empty string, or only spaces.

attachment

String

Explanation:

Attachment. (This field has been discarded.)

Range:

None

author

UserBasicDto object

Explanation:

Author details.

Range:

None

created_at

String

Explanation:

Creation time.

Constraints:

Format: yyyy-MM-ddTHH:mm:ss.SSS+08:00

updated_at

String

Explanation:

Update time.

Constraints:

Format: yyyy-MM-ddTHH:mm:ss.SSS+08:00

system

Boolean

Explanation:

Whether the comment is generated by the system.

Range:

  • true: Yes. The comment is created by the system.
  • false: No. The comment is created by a user.

noteable_id

Integer

Explanation:

MR ID.

Range:

Minimum value: 1

Maximum value: 2147483647

noteable_type

String

Explanation:

Comment type.

Range:

  • MergeRequest: Comment for MR or CR (When you select a commit under an MR or CR and add a review comment, the comment is still of the MergeRequest type).
  • Commit: Comment for code or a specific commit.

commit_id

String

Explanation:

Associated commit ID: SHA value of a commit. This field applies when noteable_type is set to Commit.

Range:

40 digits and letters.

resolvable

Boolean

Explanation:

Whether the comment needs to be resolved.

Range:

  • true: Yes
  • false or null: No

is_reply

Boolean

Explanation:

Whether the comment is a reply.

Range:

  • true: Yes. The comment is a reply.
  • false: No. The comment is a main comment.

resolved_by

UserBasicDto object

Explanation:

Comment resolver.

Range:

None

noteable_iid

Integer

Explanation:

MR IID, indicating the sequence number of the MR in the repository.

Range:

Minimum value: 1

Maximum value: 2147483647

discussion_id

String

Explanation:

Review comment ID, which is shared by the main comment and replies.

Range:

40 digits and letters.

project

String

Explanation:

Project path.

Range:

None

diff_file

String

Explanation:

File path change.

Range:

None

diff

String

Explanation:

File content change.

Range:

None

archived

Boolean

Explanation:

Whether the review comment has been archived. Archived comments cannot be edited, deleted, replied, or resolved.

Range:

  • true: Yes
  • false or null: No

review_categories

String

Explanation:

Comment type key.

The values of review_categories, review_categories_cn, and review_categories_en must match.

Range:

None

review_categories_cn

String

Explanation:

Comment type in Chinese.

The values of review_categories and review_categories_cn must match.

Range:

None

review_categories_en

String

Explanation:

Comment type in English.

The values of review_categories and review_categories_en must match.

Range:

None

review_modules

String

Explanation:

Review comment module.

Range:

None

severity

String

Explanation:

Severity. Non-suggestion reviews cannot be resolved by the assignee, MR creator, or committer.

Range:

  • suggestion
  • minor
  • major
  • fatal

severity_cn

String

Explanation:

Severity in Chinese.

Range:

  • Suggestion
  • Minor
  • Major
  • Fatal

severity_en

String

Explanation:

Severity in English.

Range:

  • Suggestion
  • Minor
  • Major
  • Fatal

file_path

String

Explanation:

File path. (This field has been discarded.)

Range:

None

line

String

Explanation:

Line number. (This field has been discarded.)

Range:

None

assignee

UserBasicDto object

Explanation:

Assignee details.

Range:

None

proposer

UserBasicDto object

Explanation:

Reviewer details.

Range:

None

position

PositionDto object

Explanation:

Code location information to associate the comment with.

Range:

None

resolved

Boolean

Explanation:

Whether the review comment has been resolved.

Range:

  • true: Yes
  • false or null: No

is_outdated

Boolean

Explanation:

Whether the review comment is for the latest commit.

Range:

  • true: Yes
  • false or null: No
Table 9 PositionDto

Parameter

Type

Description

base_sha

String

Explanation:

Base commit node of the source branch.

Range:

40 digits and letters.

start_sha

String

Explanation:

Latest commit node of the source branch.

Range:

40 digits and letters.

head_sha

String

Explanation:

Latest commit node of the target branch.

Range:

40 digits and letters.

old_path

String

Explanation:

Old file path.

Range:

None

new_path

String

Explanation:

New file path.

Range:

None

position_type

String

Explanation:

Change type.

Range:

None

Default value:

text

old_line

Integer

Explanation:

Line number before change. If the value is less than or equal to 0 or is null, the line is new and displayed in green on the right for comparison.

Range:

–1 to 2147483647 or null

new_line

Integer

Explanation:

New line No.

If the value is less than or equal to 0 or is null, the line is deleted and displayed in red on the left for comparison.

Range:

–1 to 2147483647 or null

Table 10 UserBasicDto

Parameter

Type

Description

id

Integer

Explanation:

User ID.

Range:

Minimum value: 1

Maximum value: 2147483647

name

String

Explanation:

Name.

Range:

Max. 255 characters.

username

String

Explanation:

Username.

Range:

Max. 255 characters.

state

String

Explanation:

Status.

Range:

Max. 255 characters.

avatar_url

String

Explanation:

URL for obtaining the profile picture.

Range:

None

avatar_path

String

Explanation:

Path for obtaining the profile picture.

Range:

None

email

String

Explanation:

Email address.

Range:

None

name_cn

String

Explanation:

Chinese name.

Constraints:

The value is the same as that of username. This field has been discarded.

Range:

None

web_url

String

Explanation:

Homepage URL.

Range:

None

nick_name

String

Explanation:

Alias.

Range:

None

tenant_name

String

Explanation:

Tenant name.

Range:

None

Table 11 MergeRequestVersionParamsDto

Parameter

Type

Description

diff_id

Integer

Explanation:

Each MR version has a unique diff_id. (In this API, the MR version is the latest.)

Range:

Minimum value: 1

Maximum value: 2147483647

start_sha

String

Explanation:

Latest commit node of the target branch.

Range:

40 digits and letters.

commit_id

String

Explanation:

Associated commit ID: SHA value of a commit. This field applies when noteable_type is set to Commit.

Range:

40 digits and letters.

Example Requests

POST https://{endpoint}/v2/repositories/{repository_id}/merge_requests/{merge_request_iid}/discussions

{
    "body": "Review comment",
    "lineTypes": "new",
    "position": {
        "base_sha": "a9ce1513d5185d5fe2bac52c597f204ce695c4be",
        "start_sha": "a9ce1513d5185d5fe2bac52c597f204ce695c4be",
        "head_sha": "53c75fa88dc4e7d0b68d108b7f1ee0a5c4564f44",
        "position_type": "text",
        "new_path": "a.txt",
        "old_path": "a.txt",
        "new_line": 1,
        "old_line": -1
    },
    "assignee_id": 9124,
    "proposer_id": null,
    "severity": "suggestion",
    "review_modules": "Module",
    "review_categories": "Type"
}

Example Responses

Status code: 200

OK

{
    "result": {
        "id": "996f57b8fdd5e62678b16f0ea4f91688405fa72f",
        "individual_note": false,
        "notes": [
            {
                "id": 2111974336,
                "type": "DiffNote",
                "body": "Review comment",
                "author": {
                    "id": 9124,
                    "name": "CodeHub_beta_dev",
                    "username": "c369c68f1ff84679b5a8ed904d8bff1c",
                    "state": "active",
                    "avatar_url": "",
                    "email": "liujian@example.com",
                    "name_cn": "CodeHub_beta_dev",
                    "web_url": "https://test.com/c369c68f1ff84679b5a8ed904d8bff1c",
                    "nick_name": "Alias",
                    "tenant_name": "devcloud_codehub_l00314597_01"
                },
                "created_at": "2024-07-29T22:01:37.000+08:00",
                "updated_at": "2024-07-29T22:01:37.000+08:00",
                "system": false,
                "noteable_id": 38517,
                "noteable_type": "MergeRequest",
                "resolvable": true,
                "is_reply": false,
                "noteable_iid": 18,
                "discussion_id": "996f57b8fdd5e62678b16f0ea4f91688405fa72f",
                "project": "sll_test00006/mr_test",
                "diff_file": "a.txt",
                "diff": "@@ -0,0 +1,0 @@\n+1\r\n",
                "archived": false,
                "review_categories": "Type",
                "review_categories_cn": "Type",
        "review_categories_en": "Type",
                "review_modules": "Module",
                "severity": "suggestion",
                "severity_cn": "Suggestion",
                "severity_en": "Suggestion",
                "assignee": {
                    "id": 9124,
                    "name": "CodeHub_beta_dev",
                    "username": "c369c68f1ff84679b5a8ed904d8bff1c",
                    "state": "active",
                    "avatar_url": "",
                    "email": "liujian@example.com",
                    "name_cn": "CodeHub_beta_dev",
                    "web_url": "https://test.com/c369c68f1ff84679b5a8ed904d8bff1c",
                    "nick_name": "Alias",
                    "tenant_name": "devcloud_codehub_l00314597_01"
                },
                "proposer": {
                    "id": 9124,
                    "name": "CodeHub_beta_dev",
                    "username": "c369c68f1ff84679b5a8ed904d8bff1c",
                    "state": "active",
                    "avatar_url": "",
                    "email": "liujian@example.com",
                    "name_cn": "CodeHub_beta_dev",
                    "web_url": "https://test.com/c369c68f1ff84679b5a8ed904d8bff1c",
                    "nick_name": "Alias",
                    "tenant_name": "devcloud_codehub_l00314597_01"
                },
                "position": {
                    "base_sha": "a9ce1513d5185d5fe2bac52c597f204ce695c4be",
                    "start_sha": "a9ce1513d5185d5fe2bac52c597f204ce695c4be",
                    "head_sha": "53c75fa88dc4e7d0b68d108b7f1ee0a5c4564f44",
                    "old_path": "a.txt",
                    "new_path": "a.txt",
                    "position_type": "text",
                    "new_line": 1
                },
                "resolved": false,
                "is_outdated": false
            }
        ],
        "project_id": 2111704470,
        "noteable_type": "MergeRequest",
        "project_full_path": "sll_test00006/mr_test",
        "a_mode": "0",
        "b_mode": "100644",
        "deleted_file": false,
        "new_file": true,
        "resolved": false,
        "archived": false,
                "review_categories": "Type",
        
        "review_categories_en": "Type",
                "review_modules": "Module",
        "severity": "suggestion",
        
        "severity_en": "Suggestion",
        "assignee": {
            "id": 9124,
            "name": "CodeHub_beta_dev",
            "username": "c369c68f1ff84679b5a8ed904d8bff1c",
            "state": "active",
            "avatar_url": "",
            "email": "liujian@example.com",
            "name_cn": "CodeHub_beta_dev",
            "web_url": "https://test.com/c369c68f1ff84679b5a8ed904d8bff1c",
                    "nick_name": "Alias",
            "tenant_name": "devcloud_codehub_l00314597_01"
        },
        "proposer": {
            "id": 9124,
            "name": "CodeHub_beta_dev",
            "username": "c369c68f1ff84679b5a8ed904d8bff1c",
            "state": "active",
            "avatar_url": "",
            "email": "liujian@example.com",
            "name_cn": "CodeHub_beta_dev",
            "web_url": "https://test.com/c369c68f1ff84679b5a8ed904d8bff1c",
                    "nick_name": "Alias",
            "tenant_name": "devcloud_codehub_l00314597_01"
        },
        "merge_request_version_params": {},
        "diff_file": "@@ -0,0 +1,0 @@\n+1\r\n",
        "added_lines": 2,
        "removed_lines": 0
    },
    "status": "success"
}

Status Codes

Status Code

Description

200

OK

Error Codes

Status Code

Error Code

Error Message

Description

Measure

400

CH.00401999

'body': The body is out of max length (8000 characters).

The review comment exceeds 8,000 characters.

Reduce the content.

400

CH.00401015

String cannot contain emoticons or uncommon characters

Only Unicode characters from \u0000 to \uffff can be used. Special characters, such as emojis and uncommon characters, are not supported.

Delete the special characters.

405

CH.00406019

The current MR/CR is not allowed to be reviewed after being merged, change the settings to enable this operation

The MR or CR has been merged. No more review comments can be added.

Choose Settings > Policy Settings > Merge Requests, and select Allow code review and comment for merged or closed MRs.

404

CH.00406026

MR/CR extend not found

No additional MR/CR information is found in the database.

Refresh the page and try again.

400

CH.00406029

The current MR/CR is in merging process, can not add new review

The MR/CR is being merged.

Try again later.

Parent topic:Review