讨论 API | 极狐GitLab

了解 API 中的备注类型
讨论分页
议题
Snippets
史诗
合并请求

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

讨论附加到：

Snippets
议题
史诗
合并请求
提交

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

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

了解 API 中的备注类型

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

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

讨论分页

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

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

议题

列出项目议题讨论项

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

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

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`issue_iid`	integer	是	议题的 IID。

[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Issue",
        "project_id": 5,
        "noteable_iid": null
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Issue",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Issue",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  }
]

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

获取单个议题讨论项

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

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

参数：

属性	类型	必需	描述
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`issue_iid`	integer	是	议题的 IID。
`discussion_id`	integer	是	讨论项的 ID。

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>"

创建新的议题线程

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

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

参数：

属性	类型	必需	描述
`body`	string	是	线程的内容。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`issue_iid`	integer	是	议题的 IID。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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

向现有议题线程添加备注

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

备注可以添加到评论之外的其他项目，例如系统备注，使它们成为线程。

POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes

参数：

属性	类型	必需	描述
`body`	string	是	备注或回复的内容。
`discussion_id`	integer	是	线程的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`issue_iid`	integer	是	议题的 IID。
`note_id`	integer	是	线程备注的 ID。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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"

修改现有议题线程备注

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

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

参数：

属性	类型	必需	描述
`body`	string	是	备注或回复的内容。
`discussion_id`	integer	是	线程的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`issue_iid`	integer	是	议题的 IID。
`note_id`	integer	是	线程备注的 ID。

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"

删除议题线程备注

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

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

参数：

属性	类型	必需	描述
`discussion_id`	integer	是	讨论的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`issue_iid`	integer	是	议题的 IID。
`note_id`	integer	是	讨论备注的 ID。

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636"

Snippets

列出项目代码片段讨论项

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

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

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`snippet_id`	integer	是	代码片段的 ID。

[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Snippet",
        "project_id": 5,
        "noteable_iid": null
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Snippet",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Snippet",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  }
]

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

获取单个代码片段讨论项

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

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

参数：

属性	类型	必需	描述
`discussion_id`	integer	是	讨论项的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`snippet_id`	integer	是	代码片段的 ID。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>"

创建新的代码片段线程

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

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

参数：

属性	类型	必需	描述
`body`	string	是	讨论的内容。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`snippet_id`	integer	是	代码片段的 ID。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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

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

向线程添加新备注。

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

参数：

属性	类型	必需	描述
`body`	string	是	备注或回复的内容。
`discussion_id`	integer	是	线程的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`note_id`	integer	是	线程备注的 ID。
`snippet_id`	integer	是	代码片段的 ID。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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"

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

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

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

参数：

属性	类型	必需	描述
`body`	string	是	备注或回复的内容。
`discussion_id`	integer	是	线程的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`note_id`	integer	是	线程备注的 ID。
`snippet_id`	integer	是	代码片段的 ID。

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"

删除代码片段线程备注

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

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

参数：

属性	类型	必需	描述
`discussion_id`	integer	是	讨论的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`note_id`	integer	是	讨论备注的 ID。
`snippet_id`	integer	是	代码片段的 ID。

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 或更高版本中，如果启用了史诗的新外观，则使用工作项 API代替。有关详细信息，请参阅指南如何迁移现有 API。此更改是一个重大更改。

列出群组史诗讨论项

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

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

属性	类型	必需	描述
`epic_id`	integer	是	史诗的 ID。
`id`	integer or string	是	群组的 ID 或 URL 编码路径。

[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Epic",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Epic",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Epic",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  }
]

curl --header "PRIVATE-TOKEN: <your_access_token>"\
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions"

获取单个史诗讨论项

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

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

参数：

属性	类型	必需	描述
`discussion_id`	integer	是	讨论项的 ID。
`epic_id`	integer	是	史诗的 ID。
`id`	integer or string	是	群组的 ID 或 URL 编码路径。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>"

创建新的史诗线程

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

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

参数：

属性	类型	必需	描述
`body`	string	是	线程的内容。
`epic_id`	integer	是	史诗的 ID。
`id`	integer or string	是	群组的 ID 或 URL 编码路径。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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

向现有史诗线程添加备注

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

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

参数：

属性	类型	必需	描述
`body`	string	是	备注或回复的内容。
`discussion_id`	integer	是	线程的 ID。
`epic_id`	integer	是	史诗的 ID。
`id`	integer or string	是	群组的 ID 或 URL 编码路径。
`note_id`	integer	是	线程备注的 ID。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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"

修改现有史诗线程备注

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

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

参数：

属性	类型	必需	描述
`body`	string	是	备注或回复的内容。
`discussion_id`	integer	是	线程的 ID。
`epic_id`	integer	是	史诗的 ID。
`id`	integer/string	是	群组的 ID 或 URL 编码路径。
`note_id`	integer	是	线程备注的 ID。

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"

删除史诗线程备注

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

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

参数：

属性	类型	必需	描述
`discussion_id`	integer	是	线程的 ID。
`epic_id`	integer	是	史诗的 ID。
`id`	integer or string	是	群组的 ID 或 URL 编码路径。
`note_id`	integer	是	线程备注的 ID。

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636"

合并请求

列出项目合并请求讨论项

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

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

属性	类型	必需	描述
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`merge_request_iid`	integer	是	合并请求的 IID。

[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "MergeRequest",
        "project_id": 5,
        "noteable_iid": null,
        "resolved": false,
        "resolvable": true,
        "resolved_by": null,
        "resolved_at": null
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "MergeRequest",
        "project_id": 5,
        "noteable_iid": null,
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "MergeRequest",
        "project_id": 5,
        "noteable_iid": null,
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      }
    ]
  }
]

差异评论还包含位置：

[
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": false,
    "notes": [
      {
        "id": 1128,
        "type": "DiffNote",
        "body": "diff comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "MergeRequest",
        "project_id": 5,
        "noteable_iid": null,
        "commit_id": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
        "position": {
          "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
          "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
          "head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
          "old_path": "package.json",
          "new_path": "package.json",
          "position_type": "text",
          "old_line": 27,
          "new_line": 27,
          "line_range": {
            "start": {
              "line_code": "588440f66559714280628a4f9799f0c4eb880a4a_10_10",
              "type": "new",
              "old_line": null,
              "new_line": 10
            },
            "end": {
              "line_code": "588440f66559714280628a4f9799f0c4eb880a4a_11_11",
              "type": "old",
              "old_line": 11,
              "new_line": 11
            }
          }
        },
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      }
    ]
  }
]

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

获取单个合并请求讨论项

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

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

参数：

属性	类型	必需	描述
`discussion_id`	string	是	讨论项的 ID。
`id`	integer or string	是	项目的 ID 或 URL 编码路径。
`merge_request_iid`	integer	是	合并请求的 IID。

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

创建新的合并请求线程

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

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

所有评论的参数：

属性	类型	必需	描述
`body`	string	是	线程的内容。
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`merge_request_iid`	integer	是	合并请求的 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_id`	string	否	引用提交以开始此线程的 SHA。
`created_at`	string	否	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。
`position`	hash	否	创建差异备注时的位置。
`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 坐标。

在概述页面上创建新线程

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]。如果文件中的早期更改更改了行号，这些位置可能不相同。

要创建一个新的线程：

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

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

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

[
  {
    "id": 164560414,
    "head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe",
    "base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
    "start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
    "created_at": "2021-03-30T09:18:27.351Z",
    "merge_request_id": 93958054,
    "state": "collected",
    "real_size": "2"
  },
  "previous versions are here"
]

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

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

多行评论的参数

仅用于多行评论的参数：

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

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

行代码

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

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

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

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

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

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

解决合并请求线程

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

先决条件：

您至少必须拥有开发者角色，或是正在审查的更改的作者。

PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id

参数：

属性	类型	必需	描述
`id`	integer/string	yes	项目的 ID 或 URL 编码的路径。
`discussion_id`	string	yes	线程的 ID。
`merge_request_iid`	integer	yes	合并请求的 IID。
`resolved`	boolean	yes	解决或取消解决讨论。

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"

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

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

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

参数：

属性	类型	必需	描述
`body`	string	yes	注释或回复的内容。
`id`	integer/string	yes	项目的 ID 或 URL 编码的路径。
`discussion_id`	string	yes	线程的 ID。
`merge_request_iid`	integer	yes	合并请求的 IID。
`note_id`	integer	yes	线程注释的 ID。
`created_at`	string	no	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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"

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

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

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

参数：

属性	类型	必需	描述
`discussion_id`	string	yes	线程的 ID。
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。
`merge_request_iid`	integer	yes	合并请求的 IID。
`note_id`	integer	yes	线程注释的 ID。
`body`	string	no	注释或回复的内容。必须设置 `body` 或 `resolved` 中的一个。
`resolved`	boolean	no	解决或取消解决注释。必须设置 `body` 或 `resolved` 中的一个。

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"

解决注释：

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"

删除合并请求线程注释

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

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

参数：

属性	类型	必需	描述
`discussion_id`	string	yes	线程的 ID。
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。
`merge_request_iid`	integer	yes	合并请求的 IID。
`note_id`	integer	yes	线程注释的 ID。

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

提交

列出项目提交讨论项

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

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

属性	类型	必需	描述
`commit_id`	string	yes	提交的 SHA。
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。

[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "project_id": 5,
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  }
]

差异评论还包含位置：

[
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": false,
    "notes": [
      {
        "id": 1128,
        "type": "DiffNote",
        "body": "diff comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "project_id": 5,
        "noteable_iid": null,
        "position": {
          "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
          "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
          "head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
          "old_path": "package.json",
          "new_path": "package.json",
          "position_type": "text",
          "old_line": 27,
          "new_line": 27
        },
        "resolvable": false
      }
    ]
  }
]

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions"

获取单个提交讨论项

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

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

参数：

属性	类型	必需	描述
`commit_id`	string	yes	提交的 SHA。
`discussion_id`	string	yes	讨论项的 ID。
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>"

创建新提交线程

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

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

参数：

属性	类型	必需	描述
`body`	string	yes	线程的内容。
`commit_id`	string	yes	提交的 SHA。
`id`	integer/string	yes	项目的 ID 或 URL 编码的路径。
`position[base_sha]`	string	yes (如果提供 `position*`)	父提交的 SHA。
`position[head_sha]`	string	yes (如果提供 `position*`)	此提交的 SHA。与 `commit_id` 相同。
`position[start_sha]`	string	yes (如果提供 `position*`)	父提交的 SHA。
`position[position_type]`	string	yes (如果提供 `position*`)	位置引用的类型。允许的值：`text`、`image` 或 `file`。`file` 在 GitLab 16.4 中引入。
`created_at`	string	no	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。
`position`	hash	no	创建差异注释时的位置。
`position[new_path]`	string	no	更改后的文件路径。
`position[new_line]`	integer	no	更改后的行号。
`position[old_path]`	string	no	更改前的文件路径。
`position[old_line]`	integer	no	更改前的行号。
`position[height]`	integer	no	对于 `image` 差异注释，图像高度。
`position[width]`	integer	no	对于 `image` 差异注释，图像宽度。
`position[x]`	integer	no	对于 `image` 差异注释，X 坐标。
`position[y]`	integer	no	对于 `image` 差异注释，Y 坐标。

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

添加注释到现有提交线程

向线程添加新注释。

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

参数：

属性	类型	必需	描述
`body`	string	yes	注释或回复的内容。
`commit_id`	string	yes	提交的 SHA。
`discussion_id`	string	yes	线程的 ID。
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。
`note_id`	integer	yes	线程注释的 ID。
`created_at`	string	no	日期时间字符串，ISO 8601 格式，例如 `2016-03-11T03:45:40Z`。需要管理员或项目/群组所有者权限。

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

修改现有提交线程注释

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

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

参数：

属性	类型	必需	描述
`commit_id`	string	yes	提交的 SHA。
`discussion_id`	string	yes	线程的 ID。
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。
`note_id`	integer	yes	线程注释的 ID。
`body`	string	no	注释的内容。

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"

解决注释：

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"

删除提交线程注释

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

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

参数：

属性	类型	必需	描述
`id`	integer or string	yes	项目的 ID 或 URL 编码的路径。
`commit_id`	string	yes	提交的 SHA。
`discussion_id`	string	yes	线程的 ID。
`note_id`	integer	yes	线程注释的 ID。

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"