kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/notification_settings.md
Marcel Amirault 8ac2c3ef43 Clean up EE api docs that were merged to CE 
Many small fixes to api docs which were merged from EE to CE,
and tables cleaned up, as noted in issue
https://gitlab.com/gitlab-org/gitlab-ce/issues/64072
2019-07-04 08:22:41 +00:00

6.1 KiB
Raw Blame History

Notification settings API

Introduced in GitLab 8.12.

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
  • success_pipeline
  • new_epic [ULTIMATE]

Global notification settings

Get current notification settings and email address.

GET /notification_settings

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

Example response:

{
  "level": "participating",
  "notification_email": "admin@example.com"
}

Update global notification settings

Update current notification settings and email address.

PUT /notification_settings

curl --request PUT --header "PRIVATE-TOKEN: <your_access_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
success_pipeline boolean no Enable/disable this notification
new_epic boolean no Enable/disable this notification (Introduced in 11.3) [ULTIMATE]

Example response:

{
  "level": "watch",
  "notification_email": "admin@example.com"
}

Group / project level notification settings

Get current group or project notification settings.

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

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
Attribute Type Required Description
id integer/string yes The group/project ID or path

Example response:

{
  "level": "global"
}

Update group/project level notification settings

Update current group/project notification settings.

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

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
Attribute Type Required Description
id integer/string yes The group/project ID or path
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
success_pipeline boolean no Enable/disable this notification
new_epic boolean no Enable/disable this notification (Introduced in 11.3) [ULTIMATE]

Example responses:

{
  "level": "watch"
}

{
  "level": "custom",
  "events": {
    "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,
    "failed_pipeline": false,
    "success_pipeline": false
  }
}

Users on GitLab Ultimate or Gold will also see the new_epic parameter:

{
  "level": "custom",
  "events": {
    "new_note": true,
    "new_issue": false,
    "new_epic": false,
    ...
  }
}