From 745ca5d502d6a456bbc98f3fad389f5e1633f86e Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Thu, 10 Apr 2025 13:05:44 +0200 Subject: [PATCH 01/10] Add event descriptions to Notification settings API --- doc/api/notification_settings.md | 149 ++++++++++++++++--------------- 1 file changed, 76 insertions(+), 73 deletions(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index eee35a232c5a6c..13c5355aa2d236 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -16,35 +16,38 @@ Use this API to manage settings for GitLab notifications. For more information, ## Valid notification levels -The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized: - -- `disabled` -- `participating` -- `watch` -- `global` -- `mention` -- `custom` - -If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized: - -- `new_note` -- `new_issue` -- `reopen_issue` -- `close_issue` -- `reassign_issue` -- `issue_due` -- `new_merge_request` -- `push_to_merge_request` -- `reopen_merge_request` -- `close_merge_request` -- `reassign_merge_request` -- `merge_merge_request` -- `failed_pipeline` -- `fixed_pipeline` -- `success_pipeline` -- `moved_project` -- `merge_when_pipeline_succeeds` -- `new_epic` Ultimate only. +The notification levels are defined in the `NotificationSetting.level` model enumeration: + +- `disabled`: Turn off all notifications +- `participating`: Receive notifications for threads you have participated in +- `watch`: Receive notifications for most activity +- `global`: Use your global notification settings +- `mention`: Receive notifications when you are mentioned in a comment +- `custom`: Receive notifications for selected events + +If the `custom` level is used, specific email events can be controlled. +Available events are returned by `NotificationSetting.email_events`: + +| Event | Description | +| ------------------------------ | ----------- | +| `new_note` | When someone adds a comment to an issue, merge request, or epic | +| `new_issue` | When a new issue is created | +| `reopen_issue` | When an issue is reopened | +| `close_issue` | When an issue is closed | +| `reassign_issue` | When an issue is reassigned to a different user | +| `issue_due` | When an issue is due tomorrow | +| `new_merge_request` | When a new merge request is created | +| `push_to_merge_request` | When someone pushes to a merge request | +| `reopen_merge_request` | When a merge request is reopened | +| `close_merge_request` | When a merge request is closed | +| `reassign_merge_request` | When a merge request is reassigned to a different user | +| `merge_merge_request` | When a merge request is merged | +| `failed_pipeline` | When a pipeline fails | +| `fixed_pipeline` | When a previously failed pipeline is fixed | +| `success_pipeline` | When a pipeline completes successfully | +| `moved_project` | When a project is moved | +| `merge_when_pipeline_succeeds` | When a merge request is set to merge when its pipeline succeeds | +| `new_epic` | When a new epic is created (Ultimate only) | ## Global notification settings @@ -79,28 +82,28 @@ PUT /notification_settings curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/notification_settings?level=watch" ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `level` | string | no | The global notification level | -| `notification_email` | string | no | The email address to send notifications | -| `new_note` | boolean | no | Enable/disable this notification | -| `new_issue` | boolean | no | Enable/disable this notification | -| `reopen_issue` | boolean | no | Enable/disable this notification | -| `close_issue` | boolean | no | Enable/disable this notification | -| `reassign_issue` | boolean | no | Enable/disable this notification | -| `issue_due` | boolean | no | Enable/disable this notification | -| `new_merge_request` | boolean | no | Enable/disable this notification | -| `push_to_merge_request` | boolean | no | Enable/disable this notification | -| `reopen_merge_request` | boolean | no | Enable/disable this notification | -| `close_merge_request` | boolean | no | Enable/disable this notification | -| `reassign_merge_request` | boolean | no | Enable/disable this notification | -| `merge_merge_request` | boolean | no | Enable/disable this notification | -| `failed_pipeline` | boolean | no | Enable/disable this notification | -| `fixed_pipeline` | boolean | no | Enable/disable this notification | -| `success_pipeline` | boolean | no | Enable/disable this notification | -| `moved_project` | boolean | no | Enable/disable this notification | -| `merge_when_pipeline_succeeds` | boolean | no | Enable/disable this notification | -| `new_epic` | boolean | no | Enable/disable this notification Ultimate only. | +| Attribute | Type | Required | Description | +| ------------------------------ | ------- | -------- | ----------- | +| `level` | string | no | The global notification level | +| `notification_email` | string | no | The email address to send notifications | +| `new_note` | boolean | no | Receive notifications when a new comment is added | +| `new_issue` | boolean | no | Receive notifications when a new issue is created | +| `reopen_issue` | boolean | no | Receive notifications when an issue is reopened | +| `close_issue` | boolean | no | Receive notifications when an issue is closed | +| `reassign_issue` | boolean | no | Receive notifications when an issue is reassigned | +| `issue_due` | boolean | no | Receive notifications when an issue is due tomorrow | +| `new_merge_request` | boolean | no | Receive notifications when a new merge request is created | +| `push_to_merge_request` | boolean | no | Receive notifications when someone pushes to a merge request | +| `reopen_merge_request` | boolean | no | Receive notifications when a merge request is reopened | +| `close_merge_request` | boolean | no | Receive notifications when a merge request is closed | +| `reassign_merge_request` | boolean | no | Receive notifications when a merge request is reassigned | +| `merge_merge_request` | boolean | no | Receive notifications when a merge request is merged | +| `failed_pipeline` | boolean | no | Receive notifications when a pipeline fails | +| `fixed_pipeline` | boolean | no | Receive notifications when a previously failed pipeline is fixed | +| `success_pipeline` | boolean | no | Receive notifications when a pipeline completes successfully | +| `moved_project` | boolean | no | Receive notifications when a project is moved | +| `merge_when_pipeline_succeeds` | boolean | no | Receive notifications when a merge request is set to merge when its pipeline succeeds | +| `new_epic` | boolean | no | Receive notifications when a new epic is created (Ultimate only) | Example response: @@ -151,28 +154,28 @@ curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true" ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/_index.md#namespaced-paths) | -| `level` | string | no | The global notification level | -| `new_note` | boolean | no | Enable/disable this notification | -| `new_issue` | boolean | no | Enable/disable this notification | -| `reopen_issue` | boolean | no | Enable/disable this notification | -| `close_issue` | boolean | no | Enable/disable this notification | -| `reassign_issue` | boolean | no | Enable/disable this notification | -| `issue_due` | boolean | no | Enable/disable this notification | -| `new_merge_request` | boolean | no | Enable/disable this notification | -| `push_to_merge_request` | boolean | no | Enable/disable this notification | -| `reopen_merge_request` | boolean | no | Enable/disable this notification | -| `close_merge_request` | boolean | no | Enable/disable this notification | -| `reassign_merge_request` | boolean | no | Enable/disable this notification | -| `merge_merge_request` | boolean | no | Enable/disable this notification | -| `failed_pipeline` | boolean | no | Enable/disable this notification | -| `fixed_pipeline` | boolean | no | Enable/disable this notification | -| `success_pipeline` | boolean | no | Enable/disable this notification | -| `moved_project` | boolean | no | Enable/disable this notification | -| `merge_when_pipeline_succeeds` | boolean | no | Enable/disable this notification | -| `new_epic` | boolean | no | Enable/disable this notification Ultimate only. | +| Attribute | Type | Required | Description | +| ------------------------------ | ----------------- | -------- | ----------- | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/_index.md#namespaced-paths) | +| `level` | string | no | The notification level for this group or project | +| `new_note` | boolean | no | Receive notifications when a new comment is added | +| `new_issue` | boolean | no | Receive notifications when a new issue is created | +| `reopen_issue` | boolean | no | Receive notifications when an issue is reopened | +| `close_issue` | boolean | no | Receive notifications when an issue is closed | +| `reassign_issue` | boolean | no | Receive notifications when an issue is reassigned | +| `issue_due` | boolean | no | Receive notifications when an issue is due tomorrow | +| `new_merge_request` | boolean | no | Receive notifications when a new merge request is created | +| `push_to_merge_request` | boolean | no | Receive notifications when someone pushes to a merge request | +| `reopen_merge_request` | boolean | no | Receive notifications when a merge request is reopened | +| `close_merge_request` | boolean | no | Receive notifications when a merge request is closed | +| `reassign_merge_request` | boolean | no | Receive notifications when a merge request is reassigned | +| `merge_merge_request` | boolean | no | Receive notifications when a merge request is merged | +| `failed_pipeline` | boolean | no | Receive notifications when a pipeline fails | +| `fixed_pipeline` | boolean | no | Receive notifications when a previously failed pipeline is fixed | +| `success_pipeline` | boolean | no | Receive notifications when a pipeline completes successfully | +| `moved_project` | boolean | no | Receive notifications when a project is moved | +| `merge_when_pipeline_succeeds` | boolean | no | Receive notifications when a merge request is set to merge when its pipeline succeeds | +| `new_epic` | boolean | no | Receive notifications when a new epic is created (Ultimate only) | Example responses: -- GitLab From c7e5ceefa64f00bba768196b558dbb6b945cfb52 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Thu, 10 Apr 2025 13:13:54 +0200 Subject: [PATCH 02/10] Improve style in doc --- doc/api/notification_settings.md | 189 ++++++++++++++++++++----------- 1 file changed, 121 insertions(+), 68 deletions(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 13c5355aa2d236..1b66deb3d2cdb8 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -12,11 +12,13 @@ title: Notification settings API {{< /details >}} -Use this API to manage settings for GitLab notifications. For more information, see [notification emails](../user/profile/notifications.md). +Use this API to manage notification settings in GitLab. +For more information, see [notification emails](../user/profile/notifications.md). -## Valid notification levels +## Notification levels -The notification levels are defined in the `NotificationSetting.level` model enumeration: +The notification levels are defined in the `NotificationSetting.level` model enumeration. +These levels are recognized: - `disabled`: Turn off all notifications - `participating`: Receive notifications for threads you have participated in @@ -25,31 +27,32 @@ The notification levels are defined in the `NotificationSetting.level` model enu - `mention`: Receive notifications when you are mentioned in a comment - `custom`: Receive notifications for selected events -If the `custom` level is used, specific email events can be controlled. -Available events are returned by `NotificationSetting.email_events`: +If you use the `custom` level, you can control specific email events. Available events are returned +by `NotificationSetting.email_events`. +These events are recognized: | Event | Description | | ------------------------------ | ----------- | -| `new_note` | When someone adds a comment to an issue, merge request, or epic | +| `new_note` | When someone adds a comment | | `new_issue` | When a new issue is created | | `reopen_issue` | When an issue is reopened | | `close_issue` | When an issue is closed | -| `reassign_issue` | When an issue is reassigned to a different user | +| `reassign_issue` | When an issue is reassigned | | `issue_due` | When an issue is due tomorrow | | `new_merge_request` | When a new merge request is created | | `push_to_merge_request` | When someone pushes to a merge request | | `reopen_merge_request` | When a merge request is reopened | | `close_merge_request` | When a merge request is closed | -| `reassign_merge_request` | When a merge request is reassigned to a different user | +| `reassign_merge_request` | When a merge request is reassigned | | `merge_merge_request` | When a merge request is merged | | `failed_pipeline` | When a pipeline fails | | `fixed_pipeline` | When a previously failed pipeline is fixed | | `success_pipeline` | When a pipeline completes successfully | | `moved_project` | When a project is moved | | `merge_when_pipeline_succeeds` | When a merge request is set to merge when its pipeline succeeds | -| `new_epic` | When a new epic is created (Ultimate only) | +| `new_epic` | When a new epic is created (Premium and Ultimate only) | -## Global notification settings +## Get global notification settings Get current notification settings and email address. @@ -57,10 +60,20 @@ Get current notification settings and email address. GET /notification_settings ``` +Example request: + ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/notification_settings" +curl --header "PRIVATE-TOKEN: " \ + --url "https://gitlab.example.com/api/v4/notification_settings" ``` +If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +| -------------------- | ------ | ----------- | +| `level` | string | Global notification level | +| `notification_email` | string | Email address where notifications are sent | + Example response: ```json @@ -72,38 +85,50 @@ Example response: ## Update global notification settings -Update current notification settings and email address. +Update notification settings and email address. ```plaintext PUT /notification_settings ``` +Example request: + ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/notification_settings?level=watch" +curl --request PUT --header "PRIVATE-TOKEN: " \ + --url "https://gitlab.example.com/api/v4/notification_settings?level=watch" ``` +Supported attributes: + | Attribute | Type | Required | Description | | ------------------------------ | ------- | -------- | ----------- | -| `level` | string | no | The global notification level | -| `notification_email` | string | no | The email address to send notifications | -| `new_note` | boolean | no | Receive notifications when a new comment is added | -| `new_issue` | boolean | no | Receive notifications when a new issue is created | -| `reopen_issue` | boolean | no | Receive notifications when an issue is reopened | -| `close_issue` | boolean | no | Receive notifications when an issue is closed | -| `reassign_issue` | boolean | no | Receive notifications when an issue is reassigned | -| `issue_due` | boolean | no | Receive notifications when an issue is due tomorrow | -| `new_merge_request` | boolean | no | Receive notifications when a new merge request is created | -| `push_to_merge_request` | boolean | no | Receive notifications when someone pushes to a merge request | -| `reopen_merge_request` | boolean | no | Receive notifications when a merge request is reopened | -| `close_merge_request` | boolean | no | Receive notifications when a merge request is closed | -| `reassign_merge_request` | boolean | no | Receive notifications when a merge request is reassigned | -| `merge_merge_request` | boolean | no | Receive notifications when a merge request is merged | -| `failed_pipeline` | boolean | no | Receive notifications when a pipeline fails | -| `fixed_pipeline` | boolean | no | Receive notifications when a previously failed pipeline is fixed | -| `success_pipeline` | boolean | no | Receive notifications when a pipeline completes successfully | -| `moved_project` | boolean | no | Receive notifications when a project is moved | -| `merge_when_pipeline_succeeds` | boolean | no | Receive notifications when a merge request is set to merge when its pipeline succeeds | -| `new_epic` | boolean | no | Receive notifications when a new epic is created (Ultimate only) | +| `level` | string | No | Global notification level | +| `notification_email` | string | No | Email address where notifications are sent | +| `new_note` | boolean | No | Turn on notifications when a new comment is added | +| `new_issue` | boolean | No | Turn on notifications when a new issue is created | +| `reopen_issue` | boolean | No | Turn on notifications when an issue is reopened | +| `close_issue` | boolean | No | Turn on notifications when an issue is closed | +| `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | +| `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | +| `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | +| `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | +| `reopen_merge_request` | boolean | No | Turn on notifications when a merge request is reopened | +| `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | +| `reassign_merge_request` | boolean | No | Turn on notifications when a merge request is reassigned | +| `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | +| `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | +| `fixed_pipeline` | boolean | No | Turn on notifications when a previously failed pipeline is fixed | +| `success_pipeline` | boolean | No | Turn on notifications when a pipeline completes successfully | +| `moved_project` | boolean | No | Turn on notifications when a project is moved | +| `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | +| `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | + +If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +| -------------------- | ------ | ----------- | +| `level` | string | Global notification level | +| `notification_email` | string | Email address where notifications are sent | Example response: @@ -114,23 +139,38 @@ Example response: } ``` -## Group / project level notification settings +## Get group or project notification settings -Get current group or project notification settings. +Get notification settings for a group or project. ```plaintext GET /groups/:id/notification_settings GET /projects/:id/notification_settings ``` +Example request: + +```shell +curl --header "PRIVATE-TOKEN: " \ + --url "https://gitlab.example.com/api/v4/groups/5/notification_settings" +``` + ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/notification_settings" -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/8/notification_settings" +curl --header "PRIVATE-TOKEN: " \ + --url "https://gitlab.example.com/api/v4/projects/8/notification_settings" ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/_index.md#namespaced-paths). | +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ----------------- | -------- | ----------- | +| `id` | integer or string | Yes | ID or [URL-encoded path](rest/_index.md#namespaced-paths) of the group or project | + +If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +| --------- | ------ | ----------- | +| `level` | string | Notification level | Example response: @@ -140,44 +180,55 @@ Example response: } ``` -## Update group/project level notification settings +## Update group or project notification settings -Update current group/project notification settings. +Update notification settings for a group or project. ```plaintext PUT /groups/:id/notification_settings PUT /projects/:id/notification_settings ``` +Example requests: + ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch" -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true" +curl --request PUT --header "PRIVATE-TOKEN: " \ + --url "https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch" ``` +```shell +curl --request PUT --header "PRIVATE-TOKEN: " \ + --url "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true" +``` + +Supported attributes: + | Attribute | Type | Required | Description | | ------------------------------ | ----------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/_index.md#namespaced-paths) | -| `level` | string | no | The notification level for this group or project | -| `new_note` | boolean | no | Receive notifications when a new comment is added | -| `new_issue` | boolean | no | Receive notifications when a new issue is created | -| `reopen_issue` | boolean | no | Receive notifications when an issue is reopened | -| `close_issue` | boolean | no | Receive notifications when an issue is closed | -| `reassign_issue` | boolean | no | Receive notifications when an issue is reassigned | -| `issue_due` | boolean | no | Receive notifications when an issue is due tomorrow | -| `new_merge_request` | boolean | no | Receive notifications when a new merge request is created | -| `push_to_merge_request` | boolean | no | Receive notifications when someone pushes to a merge request | -| `reopen_merge_request` | boolean | no | Receive notifications when a merge request is reopened | -| `close_merge_request` | boolean | no | Receive notifications when a merge request is closed | -| `reassign_merge_request` | boolean | no | Receive notifications when a merge request is reassigned | -| `merge_merge_request` | boolean | no | Receive notifications when a merge request is merged | -| `failed_pipeline` | boolean | no | Receive notifications when a pipeline fails | -| `fixed_pipeline` | boolean | no | Receive notifications when a previously failed pipeline is fixed | -| `success_pipeline` | boolean | no | Receive notifications when a pipeline completes successfully | -| `moved_project` | boolean | no | Receive notifications when a project is moved | -| `merge_when_pipeline_succeeds` | boolean | no | Receive notifications when a merge request is set to merge when its pipeline succeeds | -| `new_epic` | boolean | no | Receive notifications when a new epic is created (Ultimate only) | - -Example responses: +| `id` | integer or string | Yes | ID or [URL-encoded path](rest/_index.md#namespaced-paths) of the group or project | +| `level` | string | No | Notification level for this group or project | +| `new_note` | boolean | No | Turn on notifications when a new comment is added | +| `new_issue` | boolean | No | Turn on notifications when a new issue is created | +| `reopen_issue` | boolean | No | Turn on notifications when an issue is reopened | +| `close_issue` | boolean | No | Turn on notifications when an issue is closed | +| `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | +| `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | +| `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | +| `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | +| `reopen_merge_request` | boolean | No | Turn on notifications when a merge request is reopened | +| `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | +| `reassign_merge_request` | boolean | No | Turn on notifications when a merge request is reassigned | +| `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | +| `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | +| `fixed_pipeline` | boolean | No | Turn on notifications when a previously failed pipeline is fixed | +| `success_pipeline` | boolean | No | Turn on notifications when a pipeline completes successfully | +| `moved_project` | boolean | No | Turn on notifications when a project is moved | +| `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | +| `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | + +If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and one of the following response formats. + +For a simple notification level: ```json { @@ -185,6 +236,8 @@ Example responses: } ``` +For a custom notification level: + ```json { "level": "custom", @@ -208,8 +261,8 @@ Example responses: } ``` -Users on [GitLab Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` -parameter for global and group-level notification settings: +Users with Premium or Ultimate subscriptions also see the `new_epic` +parameter for global and group notification settings: ```json { -- GitLab From 37c6fd1c546c3ffeebba92c145fcd1d56e67f109 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Thu, 10 Apr 2025 13:20:13 +0200 Subject: [PATCH 03/10] Sort tables by first column a-z --- doc/api/notification_settings.md | 78 ++++++++++++++++---------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 1b66deb3d2cdb8..253d80e6b66a7e 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -33,24 +33,24 @@ These events are recognized: | Event | Description | | ------------------------------ | ----------- | -| `new_note` | When someone adds a comment | -| `new_issue` | When a new issue is created | -| `reopen_issue` | When an issue is reopened | | `close_issue` | When an issue is closed | -| `reassign_issue` | When an issue is reassigned | -| `issue_due` | When an issue is due tomorrow | -| `new_merge_request` | When a new merge request is created | -| `push_to_merge_request` | When someone pushes to a merge request | -| `reopen_merge_request` | When a merge request is reopened | | `close_merge_request` | When a merge request is closed | -| `reassign_merge_request` | When a merge request is reassigned | -| `merge_merge_request` | When a merge request is merged | | `failed_pipeline` | When a pipeline fails | | `fixed_pipeline` | When a previously failed pipeline is fixed | -| `success_pipeline` | When a pipeline completes successfully | -| `moved_project` | When a project is moved | +| `issue_due` | When an issue is due tomorrow | +| `merge_merge_request` | When a merge request is merged | | `merge_when_pipeline_succeeds` | When a merge request is set to merge when its pipeline succeeds | +| `moved_project` | When a project is moved | | `new_epic` | When a new epic is created (Premium and Ultimate only) | +| `new_issue` | When a new issue is created | +| `new_merge_request` | When a new merge request is created | +| `new_note` | When someone adds a comment | +| `push_to_merge_request` | When someone pushes to a merge request | +| `reassign_issue` | When an issue is reassigned | +| `reassign_merge_request` | When a merge request is reassigned | +| `reopen_issue` | When an issue is reopened | +| `reopen_merge_request` | When a merge request is reopened | +| `success_pipeline` | When a pipeline completes successfully | ## Get global notification settings @@ -102,26 +102,26 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------ | ------- | -------- | ----------- | -| `level` | string | No | Global notification level | -| `notification_email` | string | No | Email address where notifications are sent | -| `new_note` | boolean | No | Turn on notifications when a new comment is added | -| `new_issue` | boolean | No | Turn on notifications when a new issue is created | -| `reopen_issue` | boolean | No | Turn on notifications when an issue is reopened | | `close_issue` | boolean | No | Turn on notifications when an issue is closed | -| `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | -| `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | -| `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | -| `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | -| `reopen_merge_request` | boolean | No | Turn on notifications when a merge request is reopened | | `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | -| `reassign_merge_request` | boolean | No | Turn on notifications when a merge request is reassigned | -| `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | | `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | | `fixed_pipeline` | boolean | No | Turn on notifications when a previously failed pipeline is fixed | -| `success_pipeline` | boolean | No | Turn on notifications when a pipeline completes successfully | -| `moved_project` | boolean | No | Turn on notifications when a project is moved | +| `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | +| `level` | string | No | Global notification level | +| `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | | `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | +| `moved_project` | boolean | No | Turn on notifications when a project is moved | | `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | +| `new_issue` | boolean | No | Turn on notifications when a new issue is created | +| `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | +| `new_note` | boolean | No | Turn on notifications when a new comment is added | +| `notification_email` | string | No | Email address where notifications are sent | +| `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | +| `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | +| `reassign_merge_request` | boolean | No | Turn on notifications when a merge request is reassigned | +| `reopen_issue` | boolean | No | Turn on notifications when an issue is reopened | +| `reopen_merge_request` | boolean | No | Turn on notifications when a merge request is reopened | +| `success_pipeline` | boolean | No | Turn on notifications when a pipeline completes successfully | If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and the following response attributes: @@ -205,26 +205,26 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------ | ----------------- | -------- | ----------- | +| `close_issue` | boolean | No | Turn on notifications when an issue is closed | +| `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | +| `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | +| `fixed_pipeline` | boolean | No | Turn on notifications when a previously failed pipeline is fixed | | `id` | integer or string | Yes | ID or [URL-encoded path](rest/_index.md#namespaced-paths) of the group or project | +| `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | | `level` | string | No | Notification level for this group or project | -| `new_note` | boolean | No | Turn on notifications when a new comment is added | +| `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | +| `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | +| `moved_project` | boolean | No | Turn on notifications when a project is moved | +| `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | | `new_issue` | boolean | No | Turn on notifications when a new issue is created | -| `reopen_issue` | boolean | No | Turn on notifications when an issue is reopened | -| `close_issue` | boolean | No | Turn on notifications when an issue is closed | -| `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | -| `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | | `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | +| `new_note` | boolean | No | Turn on notifications when a new comment is added | | `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | -| `reopen_merge_request` | boolean | No | Turn on notifications when a merge request is reopened | -| `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | +| `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | | `reassign_merge_request` | boolean | No | Turn on notifications when a merge request is reassigned | -| `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | -| `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | -| `fixed_pipeline` | boolean | No | Turn on notifications when a previously failed pipeline is fixed | +| `reopen_issue` | boolean | No | Turn on notifications when an issue is reopened | +| `reopen_merge_request` | boolean | No | Turn on notifications when a merge request is reopened | | `success_pipeline` | boolean | No | Turn on notifications when a pipeline completes successfully | -| `moved_project` | boolean | No | Turn on notifications when a project is moved | -| `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | -| `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and one of the following response formats. -- GitLab From b0f678e15dae78a73bc29f4378aabc84f511ca79 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Thu, 10 Apr 2025 13:36:42 +0200 Subject: [PATCH 04/10] Document missing attributes --- doc/api/notification_settings.md | 99 +++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 32 deletions(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 253d80e6b66a7e..fb13e8fc0975b2 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -33,6 +33,8 @@ These events are recognized: | Event | Description | | ------------------------------ | ----------- | +| `approver` | A merge request you're eligible to approve is created | +| `change_reviewer_merge_request`| When a merge request's reviewer is changed | | `close_issue` | When an issue is closed | | `close_merge_request` | When a merge request is closed | | `failed_pipeline` | When a pipeline fails | @@ -41,10 +43,11 @@ These events are recognized: | `merge_merge_request` | When a merge request is merged | | `merge_when_pipeline_succeeds` | When a merge request is set to merge when its pipeline succeeds | | `moved_project` | When a project is moved | -| `new_epic` | When a new epic is created (Premium and Ultimate only) | +| `new_epic` | When a new epic is created (in the Premium and Ultimate tier) | | `new_issue` | When a new issue is created | | `new_merge_request` | When a new merge request is created | | `new_note` | When someone adds a comment | +| `new_release` | When a new release is published | | `push_to_merge_request` | When someone pushes to a merge request | | `reassign_issue` | When an issue is reassigned | | `reassign_merge_request` | When a merge request is reassigned | @@ -102,6 +105,8 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------ | ------- | -------- | ----------- | +| `approver` | boolean | No | Turn on notifications when a merge request you're eligible to approve is created | +| `change_reviewer_merge_request`| boolean | No | Turn on notifications when a merge request's reviewer is changed | | `close_issue` | boolean | No | Turn on notifications when an issue is closed | | `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | | `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | @@ -111,10 +116,11 @@ Supported attributes: | `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | | `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | | `moved_project` | boolean | No | Turn on notifications when a project is moved | -| `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | +| `new_epic` | boolean | No | Turn on notifications when a new epic is created (in the Premium and Ultimate tier) | | `new_issue` | boolean | No | Turn on notifications when a new issue is created | | `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | | `new_note` | boolean | No | Turn on notifications when a new comment is added | +| `new_release` | boolean | No | Turn on notifications when a new release is published | | `notification_email` | string | No | Email address where notifications are sent | | `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | | `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | @@ -172,7 +178,7 @@ If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and the | --------- | ------ | ----------- | | `level` | string | Notification level | -Example response: +Example response for standard notification level: ```json { @@ -180,6 +186,42 @@ Example response: } ``` +Example response for a group with custom notification level: + +```json +{ + "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 // In the Premium and Ultimate tier + } +} +``` + +In this response: + +- `true` indicates the notification is enabled. +- `false` indicates the notification is disabled. +- `null` indicates the notification uses the default setting. + ## Update group or project notification settings Update notification settings for a group or project. @@ -205,6 +247,8 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------ | ----------------- | -------- | ----------- | +| `approver` | boolean | No | Turn on notifications when a merge request you're eligible to approve is created | +| `change_reviewer_merge_request`| boolean | No | Turn on notifications when a merge request's reviewer is changed | | `close_issue` | boolean | No | Turn on notifications when an issue is closed | | `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | | `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | @@ -215,10 +259,11 @@ Supported attributes: | `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | | `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | | `moved_project` | boolean | No | Turn on notifications when a project is moved | -| `new_epic` | boolean | No | Turn on notifications when a new epic is created (Premium and Ultimate only) | +| `new_epic` | boolean | No | Turn on notifications when a new epic is created (in the Premium and Ultimate tier) | | `new_issue` | boolean | No | Turn on notifications when a new issue is created | | `new_merge_request` | boolean | No | Turn on notifications when a new merge request is created | | `new_note` | boolean | No | Turn on notifications when a new comment is added | +| `new_release` | boolean | No | Turn on notifications when a new release is published | | `push_to_merge_request` | boolean | No | Turn on notifications when someone pushes to a merge request | | `reassign_issue` | boolean | No | Turn on notifications when an issue is reassigned | | `reassign_merge_request` | boolean | No | Turn on notifications when a merge request is reassigned | @@ -236,42 +281,32 @@ For a simple notification level: } ``` -For a custom notification level: +For a custom notification level, the response includes an `events` object showing the status of each notification: ```json { "level": "custom", "events": { + "new_release": null, "new_note": true, "new_issue": false, - "reopen_issue": false, - "close_issue": false, - "reassign_issue": false, - "issue_due": false, - "new_merge_request": false, - "push_to_merge_request": false, - "reopen_merge_request": false, - "close_merge_request": false, - "reassign_merge_request": false, - "merge_merge_request": 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": false, - "success_pipeline": false - } -} -``` - -Users with Premium or Ultimate subscriptions also see the `new_epic` -parameter for global and group notification settings: - -```json -{ - "level": "custom", - "events": { - "new_note": true, - "new_issue": false, - "new_epic": false, - ... + "fixed_pipeline": null, + "success_pipeline": null, + "moved_project": false, + "merge_when_pipeline_succeeds": false, + "new_epic": null // In the Premium and Ultimate tier } } ``` -- GitLab From d7e5247088ab981b47eab94c040f4ca428c03aa9 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Fri, 11 Apr 2025 11:24:31 +0200 Subject: [PATCH 05/10] Make sentence active --- doc/api/notification_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index fb13e8fc0975b2..df6b90cc4f8928 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -248,7 +248,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------ | ----------------- | -------- | ----------- | | `approver` | boolean | No | Turn on notifications when a merge request you're eligible to approve is created | -| `change_reviewer_merge_request`| boolean | No | Turn on notifications when a merge request's reviewer is changed | +| `change_reviewer_merge_request`| boolean | No | Turn on notifications when a merge request's reviewer changes | | `close_issue` | boolean | No | Turn on notifications when an issue is closed | | `close_merge_request` | boolean | No | Turn on notifications when a merge request is closed | | `failed_pipeline` | boolean | No | Turn on notifications when a pipeline fails | -- GitLab From 49234b77c1f857cdfa9c9c05b24929faf3f06e37 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Fri, 11 Apr 2025 11:27:07 +0200 Subject: [PATCH 06/10] Use turned on/off instead of enabled/disabled --- doc/api/notification_settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index df6b90cc4f8928..d5fbb8cb68ddbc 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -218,8 +218,8 @@ Example response for a group with custom notification level: In this response: -- `true` indicates the notification is enabled. -- `false` indicates the notification is disabled. +- `true` indicates the notification is turned on. +- `false` indicates the notification is turned off. - `null` indicates the notification uses the default setting. ## Update group or project notification settings -- GitLab From 417403dd7c1605c976c6337ecadb2b7b389229cb Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Fri, 11 Apr 2025 11:31:11 +0200 Subject: [PATCH 07/10] Move note for new epic attribute --- doc/api/notification_settings.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index d5fbb8cb68ddbc..86cc28d9e069f9 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -211,7 +211,7 @@ Example response for a group with custom notification level: "success_pipeline": null, "moved_project": true, "merge_when_pipeline_succeeds": false, - "new_epic": null // In the Premium and Ultimate tier + "new_epic": null } } ``` @@ -222,6 +222,12 @@ In this response: - `false` indicates the notification is turned off. - `null` indicates the notification uses the default setting. +{{< alert type="note" >}} + +The `new_epic` attribute is available only in the Premium and Ultimate tiers. + +{{< /alert >}} + ## Update group or project notification settings Update notification settings for a group or project. @@ -306,7 +312,13 @@ For a custom notification level, the response includes an `events` object showin "success_pipeline": null, "moved_project": false, "merge_when_pipeline_succeeds": false, - "new_epic": null // In the Premium and Ultimate tier + "new_epic": null } } ``` + +{{< alert type="note" >}} + +The `new_epic` attribute is available only in the Premium and Ultimate tiers. + +{{< /alert >}} -- GitLab From 87bdb127b15796e445941078f3d2980396119e70 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Fri, 11 Apr 2025 11:32:56 +0200 Subject: [PATCH 08/10] Adjust wording to avoid "simple" --- doc/api/notification_settings.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 86cc28d9e069f9..14efa88c254e5e 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -279,7 +279,7 @@ Supported attributes: If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and one of the following response formats. -For a simple notification level: +For a non-custom notification level: ```json { @@ -317,6 +317,12 @@ For a custom notification level, the response includes an `events` object showin } ``` +In this response: + +- `true` indicates the notification is turned on. +- `false` indicates the notification is turned off. +- `null` indicates the notification uses the default setting. + {{< alert type="note" >}} The `new_epic` attribute is available only in the Premium and Ultimate tiers. -- GitLab From f0f216a930a97898d041c3faf0265e9198e6ca9d Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Fri, 11 Apr 2025 11:35:15 +0200 Subject: [PATCH 09/10] Change wording to "auto-merge" --- doc/api/notification_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 14efa88c254e5e..b18da46d0d9cb7 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -41,7 +41,7 @@ These events are recognized: | `fixed_pipeline` | When a previously failed pipeline is fixed | | `issue_due` | When an issue is due tomorrow | | `merge_merge_request` | When a merge request is merged | -| `merge_when_pipeline_succeeds` | When a merge request is set to merge when its pipeline succeeds | +| `merge_when_pipeline_succeeds` | When a merge request is set to auto-merge | | `moved_project` | When a project is moved | | `new_epic` | When a new epic is created (in the Premium and Ultimate tier) | | `new_issue` | When a new issue is created | -- GitLab From b4a82ae2e4e046e1ada47307b89cc1b24343103f Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Fri, 11 Apr 2025 11:35:43 +0200 Subject: [PATCH 10/10] Change wording to "auto-merge" 2 --- doc/api/notification_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index b18da46d0d9cb7..f80bc2ebd43e74 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -114,7 +114,7 @@ Supported attributes: | `issue_due` | boolean | No | Turn on notifications when an issue is due tomorrow | | `level` | string | No | Global notification level | | `merge_merge_request` | boolean | No | Turn on notifications when a merge request is merged | -| `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to merge when its pipeline succeeds | +| `merge_when_pipeline_succeeds` | boolean | No | Turn on notifications when a merge request is set to auto-merge | | `moved_project` | boolean | No | Turn on notifications when a project is moved | | `new_epic` | boolean | No | Turn on notifications when a new epic is created (in the Premium and Ultimate tier) | | `new_issue` | boolean | No | Turn on notifications when a new issue is created | -- GitLab