debian-mirror-gitlab/doc/api/notification_settings.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

216 lines
7.4 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
2021-06-08 01:23:25 +05:30
stage: Plan
group: Project Management
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2021-09-30 23:02:18 +05:30
# Notification settings API **(FREE)**
2016-09-29 09:46:39 +05:30
2021-09-30 23:02:18 +05:30
Change [notification settings](../user/profile/notifications.md) using the REST API.
2016-09-29 09:46:39 +05:30
2019-09-30 21:07:59 +05:30
## Valid notification levels
2016-09-29 09:46:39 +05:30
2017-08-17 22:00:37 +05:30
The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized:
2016-09-29 09:46:39 +05:30
2021-09-30 23:02:18 +05:30
- `disabled`
- `participating`
- `watch`
- `global`
- `mention`
- `custom`
2016-09-29 09:46:39 +05:30
2018-11-20 20:47:30 +05:30
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:
2016-09-29 09:46:39 +05:30
2019-09-30 21:07:59 +05:30
- `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`
2020-04-08 14:13:33 +05:30
- `fixed_pipeline`
2019-09-30 21:07:59 +05:30
- `success_pipeline`
2020-10-24 23:57:45 +05:30
- `moved_project`
2021-04-17 20:07:23 +05:30
- `merge_when_pipeline_succeeds`
2019-09-30 21:07:59 +05:30
- `new_epic` **(ULTIMATE)**
2016-09-29 09:46:39 +05:30
## Global notification settings
Get current notification settings and email address.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
GET /notification_settings
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/notification_settings"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
{
"level": "participating",
"notification_email": "admin@example.com"
}
```
## Update global notification settings
Update current notification settings and email address.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
PUT /notification_settings
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/notification_settings?level=watch"
2016-09-29 09:46:39 +05:30
```
| 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 |
2018-10-15 14:42:47 +05:30
| `issue_due` | boolean | no | Enable/disable this notification |
2016-09-29 09:46:39 +05:30
| `new_merge_request` | boolean | no | Enable/disable this notification |
2018-05-09 12:01:36 +05:30
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
2016-09-29 09:46:39 +05:30
| `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 |
2017-08-17 22:00:37 +05:30
| `failed_pipeline` | boolean | no | Enable/disable this notification |
2020-04-08 14:13:33 +05:30
| `fixed_pipeline` | boolean | no | Enable/disable this notification |
2017-08-17 22:00:37 +05:30
| `success_pipeline` | boolean | no | Enable/disable this notification |
2020-10-24 23:57:45 +05:30
| `moved_project` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30371) in GitLab 13.3) |
2021-04-17 20:07:23 +05:30
| `merge_when_pipeline_succeeds` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/244840) in GitLab 13.9) |
2020-10-24 23:57:45 +05:30
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5863) in GitLab 11.3) **(ULTIMATE)** |
2016-09-29 09:46:39 +05:30
Example response:
```json
{
"level": "watch",
"notification_email": "admin@example.com"
}
```
## Group / project level notification settings
Get current group or project notification settings.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
GET /groups/:id/notification_settings
GET /projects/:id/notification_settings
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/notification_settings"
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/8/notification_settings"
2016-09-29 09:46:39 +05:30
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/index.md#namespaced-path-encoding). |
2016-09-29 09:46:39 +05:30
Example response:
```json
{
"level": "global"
}
```
## Update group/project level notification settings
Update current group/project notification settings.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true"
2016-09-29 09:46:39 +05:30
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/index.md#namespaced-path-encoding) |
2016-09-29 09:46:39 +05:30
| `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 |
2018-10-15 14:42:47 +05:30
| `issue_due` | boolean | no | Enable/disable this notification |
2016-09-29 09:46:39 +05:30
| `new_merge_request` | boolean | no | Enable/disable this notification |
2018-05-09 12:01:36 +05:30
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
2016-09-29 09:46:39 +05:30
| `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 |
2017-08-17 22:00:37 +05:30
| `failed_pipeline` | boolean | no | Enable/disable this notification |
2020-04-08 14:13:33 +05:30
| `fixed_pipeline` | boolean | no | Enable/disable this notification |
2017-08-17 22:00:37 +05:30
| `success_pipeline` | boolean | no | Enable/disable this notification |
2020-10-24 23:57:45 +05:30
| `moved_project` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30371) in GitLab 13.3) |
2021-04-17 20:07:23 +05:30
| `merge_when_pipeline_succeeds` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/244840) in GitLab 13.9) |
2020-10-24 23:57:45 +05:30
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5863) in GitLab 11.3) **(ULTIMATE)** |
2016-09-29 09:46:39 +05:30
Example responses:
```json
{
"level": "watch"
}
2021-06-08 01:23:25 +05:30
```
2016-09-29 09:46:39 +05:30
2021-06-08 01:23:25 +05:30
```json
2016-09-29 09:46:39 +05:30
{
"level": "custom",
"events": {
"new_note": true,
"new_issue": false,
"reopen_issue": false,
"close_issue": false,
"reassign_issue": false,
2018-10-15 14:42:47 +05:30
"issue_due": false,
2016-09-29 09:46:39 +05:30
"new_merge_request": false,
2018-05-09 12:01:36 +05:30
"push_to_merge_request": false,
2016-09-29 09:46:39 +05:30
"reopen_merge_request": false,
"close_merge_request": false,
"reassign_merge_request": false,
2017-08-17 22:00:37 +05:30
"merge_merge_request": false,
"failed_pipeline": false,
2020-04-08 14:13:33 +05:30
"fixed_pipeline": false,
2017-08-17 22:00:37 +05:30
"success_pipeline": false
2016-09-29 09:46:39 +05:30
}
}
```
2021-11-11 11:23:49 +05:30
Users on [GitLab Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic`
2020-10-24 23:57:45 +05:30
parameter:
2019-09-30 21:07:59 +05:30
```json
{
"level": "custom",
"events": {
"new_note": true,
"new_issue": false,
"new_epic": false,
...
}
}
```