{{< details >}}

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

{{< /details >}}

讨论附加到:

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

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

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

了解 API 中的备注类型

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

  1. 备注:在议题、合并请求、提交或代码片段的 根部 留下的评论。
  2. 讨论:在议题、合并请求、提交或代码片段中,通常称为 线程DiscussionNotes 集合。
  3. 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"

向现有议题线程添加备注

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

{{< alert type=”warning” >}}

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

{{< /alert >}}

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"

史诗

{{< details >}}

  • Tier: 旗舰版
  • Offering: JihuLab.com,极狐GitLab 私有化部署,极狐GitLab Dedicated

{{< /details >}}

{{< alert type=”warning” >}}

在极狐GitLab 17.0 中,史诗 REST API 已弃用,并计划在 API 的第 5 版中删除。在极狐GitLab 17.4 或更高版本中,如果启用了史诗的新外观,则使用工作项 API代替。有关详细信息,请参阅指南如何迁移现有 API。此更改是一个重大更改。

{{< /alert >}}

列出群组史诗讨论项

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

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* 位置引用的类型。允许的值:textimage,或 filefile 在极狐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]。如果文件中的早期更改更改了行号,这些位置可能不相同。

要创建一个新的线程:

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

    curl --header "PRIVATE-TOKEN: <your_access_token>" \
      --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions"
    
  2. 注意最新版本的详细信息,它列在响应数组的第一个位置。

    [
      {
        "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"
    ]
    
  3. 创建一个新的差异线程。此示例在新增行上创建线程:

    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_linenew_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 注释或回复的内容。必须设置 bodyresolved 中的一个。
resolved boolean no 解决或取消解决注释。必须设置 bodyresolved 中的一个。
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*) 位置引用的类型。允许的值:textimagefilefile 在 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"