Help us learn about your current experience with the documentation. Take the survey.

通知设置 API

  • 版本：Free, Premium, Ultimate
  • 产品形态：GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 管理 GitLab 中的通知设置。 更多信息，请参阅通知邮件。

通知级别

通知级别在 NotificationSetting.level 模型枚举中定义。 支持的级别包括：

  • disabled：关闭所有通知
  • participating：接收您参与过的讨论的通知
  • watch：接收大部分活动的通知
  • global：使用您的全局通知设置
  • mention：当您在评论中被提及 时接收通知
  • custom：为选定的事件接收通知

如果您使用 custom 级别，可以控制特定的邮件事件。可用事件由 NotificationSetting.email_events 返回。 支持的事件包括：

事件 描述
approver 创建了您有权限批准的合并请求
change_reviewer_merge_request 当合并请求的审查员被更改时
close_issue 当议题被关闭时
close_merge_request 当合并请求被关闭时
failed_pipeline 当流水线失败时
fixed_pipeline 当之前失败的流水线被修复时
issue_due 当议题截止日期为明天时
merge_merge_request 当合并请求被合并时
merge_when_pipeline_succeeds 当合并请求被设置为自动合并时
moved_project 当项目被移动时
new_epic 当新的史诗被创建时（在 Premium 和 Ultimate 版本中）
new_issue 当新议题被创建时
new_merge_request 当新合并请求被创建时
new_note 当有人添加评论时
new_release 当新版本发布时
push_to_merge_request 当有人向合并请求推送代码时
reassign_issue 当议题被重新指派时
reassign_merge_request 当合并请求被重新指派时
reopen_issue 当议题被重新打开时
reopen_merge_request 当合并请求被重新打开时
success_pipeline 当流水线成功完成时

获取全局通知设置

获取当前通知设置和电子邮件地址。

GET /notification_settings

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/notification_settings"

如果成功，将返回 200 OK 和以下响应属性：

属性 类型 描述
level string 全局通知级别
notification_email string 接收通知的电子邮件地址

示例响应：

{
  "level": "participating",
  "notification_email": "[email protected]"
}

更新全局通知设置

更新通知设置和电子邮件地址。

PUT /notification_settings

示例请求：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/notification_settings?level=watch"

支持的属性：

属性 类型 必填 描述
approver boolean 否 当您有权限批准的合并请求被创建时，开启通知
change_reviewer_merge_request boolean 否 当合并请求的审查员被更改时，开启通知
close_issue boolean 否 当议题被关闭时，开启通知
close_merge_request boolean 否 当合并请求被关闭时，开启通知
failed_pipeline boolean 否 当流水线失败时，开启通知
fixed_pipeline boolean 否 当之前失败的流水线被修复时，开启通知
issue_due boolean 否 当议题截止日期为明天时，开启通知
level string 否 全局通知级别
merge_merge_request boolean 否 当合并请求被合并时，开启通知
merge_when_pipeline_succeeds boolean 否 当合并请求被设置为自动合并时，开启通知
moved_project boolean 否 当项目被移动时，开启通知
new_epic boolean 否 当新的史诗被创建时，开启通知（在 Premium 和 Ultimate 版本中）
new_issue boolean 否 当新议题被创建时，开启通知
new_merge_request boolean 否 当新合并请求被创建时，开启通知
new_note boolean 否 当有人添加评论时，开启通知
new_release boolean 否 当新版本发布时，开启通知
notification_email string 否 接收通知的电子邮件地址
push_to_merge_request boolean 否 当有人向合并请求推送代码时，开启通知
reassign_issue boolean 否 当议题被重新指派时，开启通知
reassign_merge_request boolean 否 当合并请求被重新指派时，开启通知
reopen_issue boolean 否 当议题被重新打开时，开启通知
reopen_merge_request boolean 否 当合并请求被重新打开时，开启通知
success_pipeline boolean 否 当流水线成功完成时，开启通知

如果成功，将返回 200 OK 和以下响应属性：

属性 类型 描述
level string 全局通知级别
notification_email string 接收通知的电子邮件地址

示例响应：

{
  "level": "watch",
  "notification_email": "[email protected]"
}

获取群组或项目通知设置

获取群组或项目的通知设置。

GET /groups/:id/notification_settings
GET /projects/:id/notification_settings

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/notification_settings"
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/8/notification_settings"

支持的属性：

属性 类型 必填 描述
id integer 或 string 是 群组或项目的 ID 或 URL 编码路径

如果成功，将返回 200 OK 和以下响应属性：

属性 类型 描述
level string 通知级别

标准通知级别的示例响应：

{
  "level": "global"
}

自定义通知级别的群组示例响应：

{
  "level": "custom",
  "events": {
    "new_release": null,
    "new_note": null,
    "new_issue": null,
    "reopen_issue": null,
    "close_issue": null,
    "reassign_issue": null,
    "issue_due": null,
    "new_merge_request": null,
    "push_to_merge_request": null,
    "reopen_merge_request": null,
    "close_merge_request": null,
    "reassign_merge_request": null,
    "change_reviewer_merge_request": null,
    "merge_merge_request": null,
    "failed_pipeline": null,
    "fixed_pipeline": null,
    "success_pipeline": null,
    "moved_project": true,
    "merge_when_pipeline_succeeds": false,
    "new_epic": null
  }
}

在此响应中：

  • true 表示通知已开启。
  • false 表示通知已关闭。
  • null 表示通知使用默认设置。

new_epic 属性仅在 Premium 和 Ultimate 版本中可用。

更新群组或项目通知设置

更新群组或项目的通知设置。

PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings

示例请求：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true"

支持的属性：

属性 类型 必填 描述
approver boolean 否 当您有权限批准的合并请求被创建时，开启通知
change_reviewer_merge_request boolean 否 当合并请求的审查员被更改时，开启通知
close_issue boolean 否 当议题被关闭时，开启通知
close_merge_request boolean 否 当合并请求被关闭时，开启通知
failed_pipeline boolean 否 当流水线失败时，开启通知
fixed_pipeline boolean 否 当之前失败的流水线被修复时，开启通知
id integer 或 string 是 群组或项目的 ID 或 URL 编码路径
issue_due boolean 否 当议题截止日期为明天时，开启通知
level string 否 此群组或项目的通知级别
merge_merge_request boolean 否 当合并请求被合并时，开启通知
merge_when_pipeline_succeeds boolean 否 当合并请求被设置为在其流水线成功后合并时，开启通知
moved_project boolean 否 当项目被移动时，开启通知
new_epic boolean 否 当新的史诗被创建时，开启通知（在 Premium 和 Ultimate 版本中）
new_issue boolean 否 当新议题被创建时，开启通知
new_merge_request boolean 否 当新合并请求被创建时，开启通知
new_note boolean 否 当有人添加评论时，开启通知
new_release boolean 否 当新版本发布时，开启通知
push_to_merge_request boolean 否 当有人向合并请求推送代码时，开启通知
reassign_issue boolean 否 当议题被重新指派时，开启通知
reassign_merge_request boolean 否 当合并请求被重新指派时，开启通知
reopen_issue boolean 否 当议题被重新打开时，开启通知
reopen_merge_request boolean 否 当合并请求被重新打开时，开启通知
success_pipeline boolean 否 当流水线成功完成时，开启通知

如果成功，将返回 200 OK 和以下响应格式之一。

对于非自定义通知级别：

{
  "level": "watch"
}

对于自定义通知级别，响应包含一个 events 对象，显示每个通知的状态：

{
  "level": "custom",
  "events": {
    "new_release": null,
    "new_note": true,
    "new_issue": false,
    "reopen_issue": null,
    "close_issue": null,
    "reassign_issue": null,
    "issue_due": null,
    "new_merge_request": null,
    "push_to_merge_request": null,
    "reopen_merge_request": null,
    "close_merge_request": null,
    "reassign_merge_request": null,
    "change_reviewer_merge_request": null,
    "merge_merge_request": null,
    "failed_pipeline": false,
    "fixed_pipeline": null,
    "success_pipeline": null,
    "moved_project": false,
    "merge_when_pipeline_succeeds": false,
    "new_epic": null
  }
}

在此响应中：

  • true 表示通知已开启。
  • false 表示通知已关闭。
  • null 表示通知使用默认设置。

new_epic 属性仅在 Premium 和 Ultimate 版本中可用。