极狐 GitLab Logo

讨论 API

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com，私有化部署

讨论附加到：

  1. Snippets
  2. 议题
  3. 史诗
  4. 合并请求
  5. 提交

这包括评论，线程，和系统备注。系统备注是关于对象更改的备注（例如，当里程碑更改时）。

标签备注不是此 API 的一部分，但作为单独的事件记录在资源标签事件中。

了解 API 中的备注类型#

并非所有讨论类型在 API 中都同样可用：

  1. 备注：在议题、合并请求、提交或代码片段的 根部 留下的评论。
  2. 讨论：在议题、合并请求、提交或代码片段中，通常称为 线程 的 DiscussionNotes 集合。
  3. DiscussionNote：议题、合并请求、提交或代码片段讨论中的单个项目。类型为 DiscussionNote 的项目不会作为备注 API 的一部分返回。在事件 API中不可用。

讨论分页#

默认情况下，GET 请求每次返回 20 个结果，因为 API 结果是分页的。

阅读更多关于分页的信息。

议题#

列出项目议题讨论项#

获取单个议题的所有讨论项的列表。

plaintext
GET /projects/:id/issues/:issue_iid/discussions
属性类型必需描述
idinteger/string是项目的 ID 或 URL 编码路径。
issue_iidinteger是议题的 IID。
json
1[
2  {
3    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1126,
8        "type": "DiscussionNote",
9        "body": "discussion text",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-03T21:54:39.668Z",
20        "updated_at": "2018-03-03T21:54:39.668Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "Issue",
24        "project_id": 5,
25        "noteable_iid": null
26      },
27      {
28        "id": 1129,
29        "type": "DiscussionNote",
30        "body": "reply to the discussion",
31        "attachment": null,
32        "author": {
33          "id": 1,
34          "name": "root",
35          "username": "root",
36          "state": "active",
37          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
38          "web_url": "http://localhost:3000/root"
39        },
40        "created_at": "2018-03-04T13:38:02.127Z",
41        "updated_at": "2018-03-04T13:38:02.127Z",
42        "system": false,
43        "noteable_id": 3,
44        "noteable_type": "Issue",
45        "project_id": 5,
46        "noteable_iid": null,
47        "resolvable": false
48      }
49    ]
50  },
51  {
52    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
53    "individual_note": true,
54    "notes": [
55      {
56        "id": 1128,
57        "type": null,
58        "body": "a single comment",
59        "attachment": null,
60        "author": {
61          "id": 1,
62          "name": "root",
63          "username": "root",
64          "state": "active",
65          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
66          "web_url": "http://localhost:3000/root"
67        },
68        "created_at": "2018-03-04T09:17:22.520Z",
69        "updated_at": "2018-03-04T09:17:22.520Z",
70        "system": false,
71        "noteable_id": 3,
72        "noteable_type": "Issue",
73        "project_id": 5,
74        "noteable_iid": null,
75        "resolvable": false
76      }
77    ]
78  }
79]
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions"

获取单个议题讨论项#

返回特定项目议题的单个讨论项。

plaintext
GET /projects/:id/issues/:issue_iid/discussions/:discussion_id

参数：

属性类型必需描述
idinteger or string是项目的 ID 或 URL 编码路径。
issue_iidinteger是议题的 IID。
discussion_idinteger是讨论项的 ID。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>"

创建新的议题线程#

创建单个项目议题的新线程。类似于创建备注，但以后可以添加其他评论（回复）。

plaintext
POST /projects/:id/issues/:issue_iid/discussions

参数：

属性类型必需描述
bodystring是线程的内容。
idinteger or string是项目的 ID 或 URL 编码路径。
issue_iidinteger是议题的 IID。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment"

向现有议题线程添加备注#

向线程添加新备注。这也可以通过回复标准评论创建线程。

备注可以添加到评论之外的其他项目，例如系统备注，使它们成为线程。
plaintext
POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes

参数：

属性类型必需描述
bodystring是备注或回复的内容。
discussion_idinteger是线程的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
issue_iidinteger是议题的 IID。
note_idinteger是线程备注的 ID。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes?body=comment"

修改现有议题线程备注#

修改议题的现有线程备注。

plaintext
PUT /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
bodystring是备注或回复的内容。
discussion_idinteger是线程的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
issue_iidinteger是议题的 IID。
note_idinteger是线程备注的 ID。
shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes/1108?body=comment"

删除议题线程备注#

删除议题的现有线程备注。

plaintext
DELETE /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
discussion_idinteger是讨论的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
issue_iidinteger是议题的 IID。
note_idinteger是讨论备注的 ID。
shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636"

Snippets#

列出项目代码片段讨论项#

获取单个代码片段的所有讨论项的列表。

plaintext
GET /projects/:id/snippets/:snippet_id/discussions
属性类型必需描述
idinteger/string是项目的 ID 或 URL 编码路径。
snippet_idinteger是代码片段的 ID。
json
1[
2  {
3    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1126,
8        "type": "DiscussionNote",
9        "body": "discussion text",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-03T21:54:39.668Z",
20        "updated_at": "2018-03-03T21:54:39.668Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "Snippet",
24        "project_id": 5,
25        "noteable_iid": null
26      },
27      {
28        "id": 1129,
29        "type": "DiscussionNote",
30        "body": "reply to the discussion",
31        "attachment": null,
32        "author": {
33          "id": 1,
34          "name": "root",
35          "username": "root",
36          "state": "active",
37          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
38          "web_url": "http://localhost:3000/root"
39        },
40        "created_at": "2018-03-04T13:38:02.127Z",
41        "updated_at": "2018-03-04T13:38:02.127Z",
42        "system": false,
43        "noteable_id": 3,
44        "noteable_type": "Snippet",
45        "project_id": 5,
46        "noteable_iid": null,
47        "resolvable": false
48      }
49    ]
50  },
51  {
52    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
53    "individual_note": true,
54    "notes": [
55      {
56        "id": 1128,
57        "type": null,
58        "body": "a single comment",
59        "attachment": null,
60        "author": {
61          "id": 1,
62          "name": "root",
63          "username": "root",
64          "state": "active",
65          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
66          "web_url": "http://localhost:3000/root"
67        },
68        "created_at": "2018-03-04T09:17:22.520Z",
69        "updated_at": "2018-03-04T09:17:22.520Z",
70        "system": false,
71        "noteable_id": 3,
72        "noteable_type": "Snippet",
73        "project_id": 5,
74        "noteable_iid": null,
75        "resolvable": false
76      }
77    ]
78  }
79]
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions"

获取单个代码片段讨论项#

返回特定项目代码片段的单个讨论项。

plaintext
GET /projects/:id/snippets/:snippet_id/discussions/:discussion_id

参数：

属性类型必需描述
discussion_idinteger是讨论项的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
snippet_idinteger是代码片段的 ID。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>"

创建新的代码片段线程#

创建单个项目代码片段的新线程。类似于创建备注，但以后可以添加其他评论（回复）。

plaintext
POST /projects/:id/snippets/:snippet_id/discussions

参数：

属性类型必需描述
bodystring是讨论的内容。
idinteger or string是项目的 ID 或 URL 编码路径。
snippet_idinteger是代码片段的 ID。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment"

向现有代码片段线程添加备注#

向线程添加新备注。

plaintext
POST /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes

参数：

属性类型必需描述
bodystring是备注或回复的内容。
discussion_idinteger是线程的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
note_idinteger是线程备注的 ID。
snippet_idinteger是代码片段的 ID。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes?body=comment"

修改现有代码片段线程备注#

修改代码片段的现有线程备注。

plaintext
PUT /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
bodystring是备注或回复的内容。
discussion_idinteger是线程的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
note_idinteger是线程备注的 ID。
snippet_idinteger是代码片段的 ID。
shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes/1108?body=comment"

删除代码片段线程备注#

删除代码片段的现有线程备注。

plaintext
DELETE /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
discussion_idinteger是讨论的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
note_idinteger是讨论备注的 ID。
snippet_idinteger是代码片段的 ID。
shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636"

史诗#

  • Tier: 旗舰版
  • Offering: JihuLab.com，极狐GitLab 私有化部署，极狐GitLab Dedicated
在极狐GitLab 17.0 中，史诗 REST API 已弃用，并计划在 API 的第 5 版中删除。在极狐GitLab 17.4 或更高版本中，如果启用了[史诗的新外观](../user/group/epics/epic_work_items.md)，则使用工作项 API代替。有关详细信息，请参阅[指南如何迁移现有 API](graphql/epic_work_items_api_migration_guide.md)。此更改是一个重大更改。

列出群组史诗讨论项#

获取单个史诗的所有讨论项的列表。

plaintext
GET /groups/:id/epics/:epic_id/discussions
属性类型必需描述
epic_idinteger是史诗的 ID。
idinteger or string是群组的 ID 或 URL 编码路径。
json
1[
2  {
3    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1126,
8        "type": "DiscussionNote",
9        "body": "discussion text",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-03T21:54:39.668Z",
20        "updated_at": "2018-03-03T21:54:39.668Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "Epic",
24        "project_id": 5,
25        "noteable_iid": null,
26        "resolvable": false
27      },
28      {
29        "id": 1129,
30        "type": "DiscussionNote",
31        "body": "reply to the discussion",
32        "attachment": null,
33        "author": {
34          "id": 1,
35          "name": "root",
36          "username": "root",
37          "state": "active",
38          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
39          "web_url": "http://localhost:3000/root"
40        },
41        "created_at": "2018-03-04T13:38:02.127Z",
42        "updated_at": "2018-03-04T13:38:02.127Z",
43        "system": false,
44        "noteable_id": 3,
45        "noteable_type": "Epic",
46        "project_id": 5,
47        "noteable_iid": null,
48        "resolvable": false
49      }
50    ]
51  },
52  {
53    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
54    "individual_note": true,
55    "notes": [
56      {
57        "id": 1128,
58        "type": null,
59        "body": "a single comment",
60        "attachment": null,
61        "author": {
62          "id": 1,
63          "name": "root",
64          "username": "root",
65          "state": "active",
66          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
67          "web_url": "http://localhost:3000/root"
68        },
69        "created_at": "2018-03-04T09:17:22.520Z",
70        "updated_at": "2018-03-04T09:17:22.520Z",
71        "system": false,
72        "noteable_id": 3,
73        "noteable_type": "Epic",
74        "project_id": 5,
75        "noteable_iid": null,
76        "resolvable": false
77      }
78    ]
79  }
80]
shell
curl --header "PRIVATE-TOKEN: <your_access_token>"\
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions"

获取单个史诗讨论项#

返回特定群组史诗的单个讨论项。

plaintext
GET /groups/:id/epics/:epic_id/discussions/:discussion_id

参数：

属性类型必需描述
discussion_idinteger是讨论项的 ID。
epic_idinteger是史诗的 ID。
idinteger or string是群组的 ID 或 URL 编码路径。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>"

创建新的史诗线程#

创建单个群组史诗的新线程。类似于创建备注，但以后可以添加其他评论（回复）。

plaintext
POST /groups/:id/epics/:epic_id/discussions

参数：

属性类型必需描述
bodystring是线程的内容。
epic_idinteger是史诗的 ID。
idinteger or string是群组的 ID 或 URL 编码路径。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment"

向现有史诗线程添加备注#

向线程添加新备注。这也可以通过回复标准评论创建线程。

plaintext
POST /groups/:id/epics/:epic_id/discussions/:discussion_id/notes

参数：

属性类型必需描述
bodystring是备注或回复的内容。
discussion_idinteger是线程的 ID。
epic_idinteger是史诗的 ID。
idinteger or string是群组的 ID 或 URL 编码路径。
note_idinteger是线程备注的 ID。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes?body=comment"

修改现有史诗线程备注#

修改史诗的现有线程备注。

plaintext
PUT /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
bodystring是备注或回复的内容。
discussion_idinteger是线程的 ID。
epic_idinteger是史诗的 ID。
idinteger/string是群组的 ID 或 URL 编码路径。
note_idinteger是线程备注的 ID。
shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes/1108?body=comment"

删除史诗线程备注#

删除史诗的现有线程备注。

plaintext
DELETE /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
discussion_idinteger是线程的 ID。
epic_idinteger是史诗的 ID。
idinteger or string是群组的 ID 或 URL 编码路径。
note_idinteger是线程备注的 ID。
shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636"

合并请求#

列出项目合并请求讨论项#

获取单个合并请求的所有讨论项的列表。

plaintext
GET /projects/:id/merge_requests/:merge_request_iid/discussions
属性类型必需描述
idinteger or string是项目的 ID 或 URL 编码路径。
merge_request_iidinteger是合并请求的 IID。
json
1[
2  {
3    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1126,
8        "type": "DiscussionNote",
9        "body": "discussion text",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-03T21:54:39.668Z",
20        "updated_at": "2018-03-03T21:54:39.668Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "MergeRequest",
24        "project_id": 5,
25        "noteable_iid": null,
26        "resolved": false,
27        "resolvable": true,
28        "resolved_by": null,
29        "resolved_at": null
30      },
31      {
32        "id": 1129,
33        "type": "DiscussionNote",
34        "body": "reply to the discussion",
35        "attachment": null,
36        "author": {
37          "id": 1,
38          "name": "root",
39          "username": "root",
40          "state": "active",
41          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
42          "web_url": "http://localhost:3000/root"
43        },
44        "created_at": "2018-03-04T13:38:02.127Z",
45        "updated_at": "2018-03-04T13:38:02.127Z",
46        "system": false,
47        "noteable_id": 3,
48        "noteable_type": "MergeRequest",
49        "project_id": 5,
50        "noteable_iid": null,
51        "resolved": false,
52        "resolvable": true,
53        "resolved_by": null
54      }
55    ]
56  },
57  {
58    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
59    "individual_note": true,
60    "notes": [
61      {
62        "id": 1128,
63        "type": null,
64        "body": "a single comment",
65        "attachment": null,
66        "author": {
67          "id": 1,
68          "name": "root",
69          "username": "root",
70          "state": "active",
71          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
72          "web_url": "http://localhost:3000/root"
73        },
74        "created_at": "2018-03-04T09:17:22.520Z",
75        "updated_at": "2018-03-04T09:17:22.520Z",
76        "system": false,
77        "noteable_id": 3,
78        "noteable_type": "MergeRequest",
79        "project_id": 5,
80        "noteable_iid": null,
81        "resolved": false,
82        "resolvable": true,
83        "resolved_by": null
84      }
85    ]
86  }
87]

差异评论还包含位置：

json
1[
2  {
3    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1128,
8        "type": "DiffNote",
9        "body": "diff comment",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-04T09:17:22.520Z",
20        "updated_at": "2018-03-04T09:17:22.520Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "MergeRequest",
24        "project_id": 5,
25        "noteable_iid": null,
26        "commit_id": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
27        "position": {
28          "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
29          "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
30          "head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
31          "old_path": "package.json",
32          "new_path": "package.json",
33          "position_type": "text",
34          "old_line": 27,
35          "new_line": 27,
36          "line_range": {
37            "start": {
38              "line_code": "588440f66559714280628a4f9799f0c4eb880a4a_10_10",
39              "type": "new",
40              "old_line": null,
41              "new_line": 10
42            },
43            "end": {
44              "line_code": "588440f66559714280628a4f9799f0c4eb880a4a_11_11",
45              "type": "old",
46              "old_line": 11,
47              "new_line": 11
48            }
49          }
50        },
51        "resolved": false,
52        "resolvable": true,
53        "resolved_by": null
54      }
55    ]
56  }
57]
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"

获取单个合并请求讨论项#

返回特定项目合并请求的单个讨论项。

plaintext
GET /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id

参数：

属性类型必需描述
discussion_idstring是讨论项的 ID。
idinteger or string是项目的 ID 或 URL 编码路径。
merge_request_iidinteger是合并请求的 IID。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>"

创建新的合并请求线程#

创建单个项目合并请求的新线程。类似于创建备注，但以后可以添加其他评论（回复）。有关其他方法，请参阅提交 API 中的提交评论到提交，以及备注 API 中的创建新的合并请求备注。

plaintext
POST /projects/:id/merge_requests/:merge_request_iid/discussions

所有评论的参数：

属性类型必需描述
bodystring是线程的内容。
idinteger/string是项目的 ID 或 URL 编码路径。
merge_request_iidinteger是合并请求的 IID。
position[base_sha]string是（如果提供 position*）源分支中的基础提交 SHA。
position[head_sha]string是（如果提供 position*）引用此合并请求 HEAD 的 SHA。
position[start_sha]string是（如果提供 position*）引用目标分支提交的 SHA。
position[new_path]string是（如果位置类型是 text）更改后的文件路径。
position[old_path]string是（如果位置类型是 text）更改前的文件路径。
position[position_type]string是（如果提供 position*）位置引用的类型。允许的值：text，image，或 file。file 在极狐GitLab 16.4 中引入。
commit_idstring否引用提交以开始此线程的 SHA。
created_atstring否日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
positionhash否创建差异备注时的位置。
position[new_line]integer否对于 text 差异备注，更改后的行号。
position[old_line]integer否对于 text 差异备注，更改前的行号。
position[line_range]hash否多行差异备注的行范围。
position[width]integer否对于 image 差异备注，图像的宽度。
position[height]integer否对于 image 差异备注，图像的高度。
position[x]float否对于 image 差异备注，X 坐标。
position[y]float否对于 image 差异备注，Y 坐标。

在概述页面上创建新线程#

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"

创建合并请求差异中的新线程

  • position[old_path] 和 position[new_path] 是必需的，必须引用变更前后的文件路径。
  • 要在新增行（在合并请求差异中以绿色突出显示）上创建线程，请使用 position[new_line]，并且不要包含 position[old_line]。
  • 要在移除行（在合并请求差异中以红色突出显示）上创建线程，请使用 position[old_line]，并且不要包含 position[new_line]。
  • 要在未更改的行上创建线程，请为该行包含 position[new_line] 和 position[old_line]。如果文件中的早期更改更改了行号，这些位置可能不相同。

要创建一个新的线程：

  1. 获取最新的合并请求版本:

    shell
    curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions"

  2. 注意最新版本的详细信息，它列在响应数组的第一个位置。

    json
    1[
2  {
3    "id": 164560414,
4    "head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe",
5    "base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
6    "start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
7    "created_at": "2021-03-30T09:18:27.351Z",
8    "merge_request_id": 93958054,
9    "state": "collected",
10    "real_size": "2"
11  },
12  "previous versions are here"
13]

  3. 创建一个新的差异线程。此示例在新增行上创建线程：

    shell
    1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>"\
3  --form 'position[position_type]=text'\
4  --form 'position[base_sha]=<use base_commit_sha from the versions response>'\
5  --form 'position[head_sha]=<use head_commit_sha from the versions response>'\
6  --form 'position[start_sha]=<use start_commit_sha from the versions response>'\
7  --form 'position[new_path]=file.js'\
8  --form 'position[old_path]=file.js'\
9  --form 'position[new_line]=18'\
10  --form 'body=test comment body'\
11  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"

多行评论的参数

仅用于多行评论的参数：

属性类型必需描述
position[line_range][end][line_code]stringyes结束行的行代码。
position[line_range][end][type]stringyes对于此提交添加的行，使用 new，否则使用 old。
position[line_range][end][old_line]integerno结束行的旧行号。
position[line_range][end][new_line]integerno结束行的新行号。
position[line_range][start][line_code]stringyes起始行的行代码。
position[line_range][start][type]stringyes对于此提交添加的行，使用 new，否则使用 old。
position[line_range][start][old_line]integerno起始行的旧行号。
position[line_range][start][new_line]integerno起始行的新行号。
position[line_range][end]hashno多行注释的结束行。
position[line_range][start]hashno多行注释的起始行。

line_range 属性中的 old_line 和 new_line 参数显示多行评论的范围。例如，“评论于第 +296 至 +297 行”。

行代码

行代码的形式为 <SHA>_<old>_<new>，例如：adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5

  • <SHA> 是文件名的 SHA1 哈希。
  • <old> 是更改前的行号。
  • <new> 是更改后的行号。

例如，如果某个提交（<COMMIT_ID>）删除了 README 中的第 463 行，您可以通过引用旧文件中的第 463 行来评论删除：

shell
1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --form "note=Very clever to remove this unnecessary line!" \
4  --form "path=README" \
5  --form "line=463" \
6  --form "line_type=old" \
7  --url "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments"

如果某个提交（<COMMIT_ID>）向 hello.rb 添加了第 157 行，您可以通过引用新文件中的第 157 行来评论添加：

shell
1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --form "note=This is brilliant!" \
4  --form "path=hello.rb" \
5  --form "line=157" \
6  --form "line_type=new" \
7  --url "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments"

解决合并请求线程

解决或取消解决合并请求中的讨论线程。

先决条件：

  • 您至少必须拥有开发者角色，或是正在审查的更改的作者。
plaintext
PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id

参数：

属性类型必需描述
idinteger/stringyes项目的 ID 或 URL 编码的路径。
discussion_idstringyes线程的 ID。
merge_request_iidintegeryes合并请求的 IID。
resolvedbooleanyes解决或取消解决讨论。
shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>?resolved=true"

添加注释到现有合并请求线程

添加新注释到线程。这也可以通过回复标准评论创建线程。

plaintext
POST /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes

参数：

属性类型必需描述
bodystringyes注释或回复的内容。
idinteger/stringyes项目的 ID 或 URL 编码的路径。
discussion_idstringyes线程的 ID。
merge_request_iidintegeryes合并请求的 IID。
note_idintegeryes线程注释的 ID。
created_atstringno日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes?body=comment"

修改现有合并请求线程注释

修改或解决合并请求的现有线程注释。

plaintext
PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
discussion_idstringyes线程的 ID。
idinteger or stringyes项目的 ID 或 URL 编码的路径。
merge_request_iidintegeryes合并请求的 IID。
note_idintegeryes线程注释的 ID。
bodystringno注释或回复的内容。必须设置 body 或 resolved 中的一个。
resolvedbooleanno解决或取消解决注释。必须设置 body 或 resolved 中的一个。
shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?body=comment"

解决注释：

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?resolved=true"

删除合并请求线程注释

删除合并请求的现有线程注释。

plaintext
DELETE /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
discussion_idstringyes线程的 ID。
idinteger or stringyes项目的 ID 或 URL 编码的路径。
merge_request_iidintegeryes合并请求的 IID。
note_idintegeryes线程注释的 ID。
shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636"

提交

列出项目提交讨论项

获取单个提交的所有讨论项的列表。

plaintext
GET /projects/:id/repository/commits/:commit_id/discussions
属性类型必需描述
commit_idstringyes提交的 SHA。
idinteger or stringyes项目的 ID 或 URL 编码的路径。
json
1[
2  {
3    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1126,
8        "type": "DiscussionNote",
9        "body": "discussion text",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-03T21:54:39.668Z",
20        "updated_at": "2018-03-03T21:54:39.668Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "Commit",
24        "project_id": 5,
25        "noteable_iid": null,
26        "resolvable": false
27      },
28      {
29        "id": 1129,
30        "type": "DiscussionNote",
31        "body": "reply to the discussion",
32        "attachment": null,
33        "author": {
34          "id": 1,
35          "name": "root",
36          "username": "root",
37          "state": "active",
38          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
39          "web_url": "http://localhost:3000/root"
40        },
41        "created_at": "2018-03-04T13:38:02.127Z",
42        "updated_at": "2018-03-04T13:38:02.127Z",
43        "system": false,
44        "noteable_id": 3,
45        "noteable_type": "Commit",
46        "project_id": 5,
47        "noteable_iid": null,
48        "resolvable": false
49      }
50    ]
51  },
52  {
53    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
54    "individual_note": true,
55    "notes": [
56      {
57        "id": 1128,
58        "type": null,
59        "body": "a single comment",
60        "attachment": null,
61        "author": {
62          "id": 1,
63          "name": "root",
64          "username": "root",
65          "state": "active",
66          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
67          "web_url": "http://localhost:3000/root"
68        },
69        "created_at": "2018-03-04T09:17:22.520Z",
70        "updated_at": "2018-03-04T09:17:22.520Z",
71        "system": false,
72        "noteable_id": 3,
73        "noteable_type": "Commit",
74        "project_id": 5,
75        "noteable_iid": null,
76        "resolvable": false
77      }
78    ]
79  }
80]

差异评论还包含位置：

json
1[
2  {
3    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
4    "individual_note": false,
5    "notes": [
6      {
7        "id": 1128,
8        "type": "DiffNote",
9        "body": "diff comment",
10        "attachment": null,
11        "author": {
12          "id": 1,
13          "name": "root",
14          "username": "root",
15          "state": "active",
16          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
17          "web_url": "http://localhost:3000/root"
18        },
19        "created_at": "2018-03-04T09:17:22.520Z",
20        "updated_at": "2018-03-04T09:17:22.520Z",
21        "system": false,
22        "noteable_id": 3,
23        "noteable_type": "Commit",
24        "project_id": 5,
25        "noteable_iid": null,
26        "position": {
27          "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
28          "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
29          "head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
30          "old_path": "package.json",
31          "new_path": "package.json",
32          "position_type": "text",
33          "old_line": 27,
34          "new_line": 27
35        },
36        "resolvable": false
37      }
38    ]
39  }
40]
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions"

获取单个提交讨论项

返回特定项目提交的单个讨论项

plaintext
GET /projects/:id/repository/commits/:commit_id/discussions/:discussion_id

参数：

属性类型必需描述
commit_idstringyes提交的 SHA。
discussion_idstringyes讨论项的 ID。
idinteger or stringyes项目的 ID 或 URL 编码的路径。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>"

创建新提交线程

为单个项目提交创建新线程。类似于创建注释，但可以在以后添加其他评论（回复）。

plaintext
POST /projects/:id/repository/commits/:commit_id/discussions

参数：

属性类型必需描述
bodystringyes线程的内容。
commit_idstringyes提交的 SHA。
idinteger/stringyes项目的 ID 或 URL 编码的路径。
position[base_sha]stringyes (如果提供 position*)父提交的 SHA。
position[head_sha]stringyes (如果提供 position*)此提交的 SHA。与 commit_id 相同。
position[start_sha]stringyes (如果提供 position*)父提交的 SHA。
position[position_type]stringyes (如果提供 position*)位置引用的类型。允许的值：text、image 或 file。file 在 GitLab 16.4 中引入。
created_atstringno日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
positionhashno创建差异注释时的位置。
position[new_path]stringno更改后的文件路径。
position[new_line]integerno更改后的行号。
position[old_path]stringno更改前的文件路径。
position[old_line]integerno更改前的行号。
position[height]integerno对于 image 差异注释，图像高度。
position[width]integerno对于 image 差异注释，图像宽度。
position[x]integerno对于 image 差异注释，X 坐标。
position[y]integerno对于 image 差异注释，Y 坐标。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions?body=comment"

创建 API 请求的规则与在合并请求差异中创建新线程时相同。例外情况：

  • base_sha
  • head_sha
  • start_sha

添加注释到现有提交线程

向线程添加新注释。

plaintext
POST /projects/:id/repository/commits/:commit_id/discussions/:discussion_id/notes

参数：

属性类型必需描述
bodystringyes注释或回复的内容。
commit_idstringyes提交的 SHA。
discussion_idstringyes线程的 ID。
idinteger or stringyes项目的 ID 或 URL 编码的路径。
note_idintegeryes线程注释的 ID。
created_atstringno日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/群组所有者权限。
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes?body=comment

修改现有提交线程注释

修改或解决提交的现有线程注释。

plaintext
PUT /projects/:id/repository/commits/:commit_id/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
commit_idstringyes提交的 SHA。
discussion_idstringyes线程的 ID。
idinteger or stringyes项目的 ID 或 URL 编码的路径。
note_idintegeryes线程注释的 ID。
bodystringno注释的内容。
shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes/1108?body=comment"

解决注释：

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes/1108?resolved=true"

删除提交线程注释

删除提交的现有线程注释。

plaintext
DELETE /projects/:id/repository/commits/:commit_id/discussions/:discussion_id/notes/:note_id

参数：

属性类型必需描述
idinteger or stringyes项目的 ID 或 URL 编码的路径。
commit_idstringyes提交的 SHA。
discussion_idstringyes线程的 ID。
note_idintegeryes线程注释的 ID。
shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes/636"