Creating an MR Review_Review_APIs_API Reference

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.

Creating an MR Review

Function

URI

Request Parameters

Response Parameters

Example Requests

Example Responses

Status Codes

Error Codes

Feedback

Was this page helpful?

Feedback