info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# GitLab Notification Emails **(FREE)**
# Notification emails **(FREE)**
GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications
enabled, you can receive updates about activity in issues, merge requests, epics, and designs.
Notifications are sent via email.
Stay informed about what's happening in GitLab with email notifications.
You can receive updates about activity in issues, merge requests, epics, and designs.
For the tool that enables GitLab administrators to send messages to users, read
For the tool that GitLab administrators can use to send messages to users, read
[Email from GitLab](../../tools/email.md).
## Receiving notifications
## Receive notifications
You receive notifications for one of the following reasons:
- You participate in an issue, merge request, epic, or design. In this context, _participate_ means comment, or edit.
- You [enable notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics).
- You participate in an issue, merge request, epic, or design. In this context, _participate_ means
comment or edit.
- You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics).
- You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level.
While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic.
NOTE:
Notifications can be blocked by an administrator, preventing them from being sent.
Administrators can block notifications, preventing them from being sent.
## Tuning your notifications
## Tune your notifications
The number of notifications can be overwhelming. GitLab allows you to tune the notifications you receive.
Getting many notifications can be overwhelming. You can tune the notifications you receive.
For example, you might want to be notified about all activity in a specific project.
For other projects, you only need to be notified when you are mentioned by name.
For other projects, you only want to be notified when you are mentioned by name.
You can tune the notifications you receive by combining your notification settings:
You can tune the notifications you receive by changing your notification settings:
For a demonstration of how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4).
#### Group notification email address
#### Group notifications
You can select a notification level and email address for each group.
To select a notification level for a group, use either of these methods:
You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate.
1. In the top-right corner, select your avatar.
1. Select **Preferences**.
1. In the left sidebar, select **Notifications**.
1. Locate the project in the **Groups** section.
1. Select the desired [notification level](#notification-levels).
---
1. Go to your group.
1. Select the notification dropdown, marked with a bell icon (**{notifications}**).
1. Select the desired [notification level](#notification-levels).
1. Select the desired email address.
##### Group notification email address
### Project notifications
> Introduced in GitLab 12.0
You can select a notification level for each project to help you closely monitor activity in select projects.
You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate.
To select a notification level for a project, use either of these methods:
1. In the top-right corner, select your avatar.
1. Select **Preferences**.
1. In the left sidebar, select **Notifications**.
1. Locate the project in the **Groups** section.
1. Select the desired email address.
1. Locate the project in the **Projects** section.
1. Select the desired [notification level](#notification-levels).
Or:
1. On the top bar, select **Menu > Projects** and find your project.
1. Select the notification dropdown, next to the bell icon (**{notifications}**).
1. Select the desired [notification level](#notification-levels).
| Group access level changed | User | Sent when user group access level is changed |
| New email added | User | Security email, always sent. |
| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 |
| New SSH key added | User | Security email, always sent. |
| New user created | User | Sent on user creation, except for OmniAuth (LDAP)|
| Password changed | User | Security email, always sent when user changes their own password |
| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user |
| New user created | User | Sent on user creation, except for OmniAuth (LDAP)|
| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 |
| User added to project | User | Sent when user is added to project |
| Personal access tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. |
| Personal access tokens have expired | User | Security email, always sent. |
| Project access level changed | User | Sent when user project access level is changed |
| SSH key has expired | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 |
| User added to group | User | Sent when user is added to group |
| Group access level changed | User | Sent when user group access level is changed |
| Personal Access Tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. |
| Personal Access Tokens have expired | User | Security email, always sent. |
| Project moved | Project members (1) | (1) not disabled |
| New release | Project members | Custom notification |
| User added to project | User | Sent when user is added to project |
## Notifications on issues, merge requests, and epics
To enable notifications on one specific issue, merge request or epic, you need to enable the **Notifications** toggle in the right sidebar.
To enable notifications on a specific issue, merge request, or epic, you must turn on the
**Notifications** toggle in the right sidebar.
-**Enable**: If you are not a participant in the discussion on that issue, but
want to receive notifications on each update, subscribe to it.
-**Disable**: If you are receiving notifications for updates to that issue but no
longer want to receive them, unsubscribe from it.
-To subscribe, **turn on** if you are not a participant in the discussion, but want to receive
notifications on each update.
-To unsubscribe, **turn off** if you are receiving notifications for updates but no longer want to
receive them, unsubscribe from it.
Disabling this toggle only unsubscribes you from updates related to this issue, merge request, or epic.
Turning this toggle off only unsubscribes you from updates related to this issue, merge request, or epic.
Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails).
Enabling this notification on an epic doesn't automatically subscribe you to the issues linked
Turning notifications on in an epic doesn't automatically subscribe you to the issues linked
to the epic.
For most events, the notification is sent to:
- Participants:
- The author and assignee of the issue/merge request.
- Authors of comments on the issue/merge request.
- Anyone mentioned by `@username` in the title or description of the issue, merge request or epic.
- Anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic.
- Authors of comments.
- Anyone [mentioned](../project/issues/issue_data_and_actions.md#mentions) by username in the title
or description of the issue, merge request or epic.
- Anyone with notification level "Participating" or higher that is mentioned by their username in
any of the comments on the issue, merge request, or epic.
- Watchers: users with notification level "Watch".
- Subscribers: anyone who manually subscribed to the issue, merge request, or epic.
- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below.
- Custom: Users with notification level "custom" who turned on notifications for any of the events in the following table.
NOTE:
To minimize the number of notifications that do not require any action, in
...
...
@@ -259,16 +261,17 @@ If the title or description of an issue or merge request is
changed, notifications are sent to any **new** mentions by `@username` as
if they had been mentioned in the original text.
You don't receive notifications for issues, merge requests or milestones created
by yourself (except when an issue is due). You only receive automatic
notifications when somebody else comments or adds changes to the ones that
you've created or mentions you.
BNy default, you don't receive notifications for issues, merge requests, or epics created
by yourself. You only receive notifications when somebody else comments or adds changes to the ones
that you've created or mentions you, or when an issue is due soon.
To always receive notifications on your own issues and so on, you must turn on
[notifications about your own activity](#global-notification-settings).
If an open merge request becomes unmergeable due to conflict, its author is notified about the cause.
If a user has also set the merge request to automatically merge once pipeline succeeds,
If a user has also set the merge request to automatically merge when pipeline succeeds,
then that user is also notified.
## Design email notifications
## Notifications on designs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6.
...
...
@@ -284,7 +287,7 @@ The participants are:
If you no longer wish to receive any email notifications:
1.[Go to the Notifications settings page.](#editing-notification-settings)
1.[Go to the Notifications settings page.](#edit-notification-settings)
1. Clear the **Receive product marketing emails** checkbox.
1. Set your **Global notification level** to **Disabled**.
1. Clear the **Receive notifications about your own activity** checkbox.
...
...
@@ -295,7 +298,7 @@ On self-managed installations, even after doing this, your instance administrato
[can still email you](../../tools/email.md).
To unsubscribe, select the unsubscribe link in one of these emails.
## Filtering email
## Filter email
Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue.
