Notification emails

Version history

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 GitLab administrators can use to send messages to users, read Email from GitLab.

Who receives notifications

When notifications are enabled for an issue, merge request, or epic, GitLab notifies you of actions that happen there.

You might receive notifications for one of the following reasons:

  1. GitLab doesn’t send a notification when a comment is edited to include a user mention.
note
Administrators can block notifications, preventing them from being sent.

Edit notification settings

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 want to be notified when you are mentioned by name.

These notification settings apply only to you. They do not affect the notifications received by anyone else.

To edit your notification settings:

  1. On the left sidebar, select your avatar.
  2. Select Preferences.
  3. On the left sidebar, select Notifications.
  4. Edit the desired global, group, or project notification settings. Edited settings are automatically saved.

Notification scope

You can tune the scope of your notifications by selecting different notification levels for each project and group.

Notification scope is applied from the broadest to most specific levels:

  • Your global, or default, notification level applies if you have not selected a notification level for the project or group in which the activity occurred.
  • Your group setting overrides your default setting.
  • Your project setting overrides the group setting.

Notification levels

For each project and group you can select one of the following levels:

LevelDescription
GlobalYour global settings apply.
WatchReceive notifications for any activity.
ParticipateReceive notifications for threads you have participated in.
On mentionReceive notifications when you are mentioned in a comment.
DisabledReceive no notifications.
CustomReceive notifications for selected events and threads you have participated in.

Global notification settings

Your Global notification settings are the default settings unless you select different values for a project or a group.

  • Notification email: the email address your notifications are sent to. Defaults to your primary email address.
  • Receive product marketing emails: select this checkbox to receive periodic emails about GitLab features.
  • Global notification level: the default notification level which applies to all your notifications.
  • Receive notifications about your own activity: select this checkbox to receive notifications about your own activity. Not selected by default.

Group notifications

You can select a notification level and email address for each group.

Change level of group notifications

To select a notification level for a group, use either of these methods:

  1. On the left sidebar, select your avatar.
  2. Select Preferences.
  3. On the left sidebar, select Notifications.
  4. Locate the project in the Groups section.
  5. Select the desired notification level.

Or:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select the notification dropdown list, next to the bell icon ().
  3. Select the desired notification level.

Change email address used for group notifications

Introduced in GitLab 12.0.

You can select an email address to receive notifications for each group you belong to. You can use group notifications, for example, if you work freelance, and want to keep email about clients’ projects separate.

  1. On the left sidebar, select your avatar.
  2. Select Preferences.
  3. On the left sidebar, select Notifications.
  4. Locate the project in the Groups section.
  5. Select the desired email address.

Change level of project notifications

To help you stay up to date, you can select a notification level for each project.

To select a notification level for a project, use either of these methods:

  1. On the left sidebar, select your avatar.
  2. Select Preferences.
  3. On the left sidebar, select Notifications.
  4. Locate the project in the Projects section.
  5. Select the desired notification level.

Or:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select the notification dropdown list, next to the bell icon ().
  3. Select the desired notification level.

To learn how to be notified when a new release is available, watch Notification for releases.

Opt out of product marketing emails

You can receive emails that teach you about various GitLab features. These emails are enabled by default.

To opt out:

  1. On the left sidebar, select your avatar.
  2. Select Preferences.
  3. On the left sidebar, select Notifications.
  4. Clear the Receive product marketing emails checkbox. Edited settings are automatically saved and enabled.

Disabling these emails does not disable all emails. Learn how to opt out of all emails from GitLab.

Self-managed product marketing emails

The self-managed installation generates and automatically sends these emails based on user actions. Turning this on does not cause your GitLab instance or your company to send any personal information to GitLab Inc.

An instance administrator can configure this setting for all users. If you choose to opt out, your setting overrides the instance-wide setting, even when an administrator later enables these emails for all users.

Notification events

Users are notified of the following events:

EventSent toSettings level
New releaseProject membersCustom notification.
Project movedProject membersAny other than disabled.
Email changedUserSecurity email, always sent.
Group access level changedUserSent when user group access level is changed.
New email address addedUserSecurity email, sent to primary email address. Introduced in GitLab 14.9.
New email address addedUserSecurity email, sent to newly-added email address.
New SAML/SCIM user provisionedUserSent when a user is provisioned through SAML/SCIM. Introduced in GitLab 13.8.
New SSH key addedUserSecurity email, always sent.
New user createdUserSent on user creation, except for OmniAuth (LDAP).
Password changedUserSecurity email, always sent when user changes their own password.
Password changed by administratorUserSecurity email, always sent when an administrator changes the password of another user.
Personal access tokens expiring soonUserSecurity email, always sent.
Personal access tokens have been createdUserSecurity email, always sent. Introduced in GitLab 14.9.
Personal access tokens have expiredUserSecurity email, always sent.
Personal access token has been revokedUserSecurity email, always sent. Introduced in GitLab 15.5.
Project access level changedUserSent when user project access level is changed.
SSH key has expiredUserSecurity email, always sent. Introduced in GitLab 13.12.
Two-factor authentication disabledUserSecurity email, always sent.
User added to groupUserSent when user is added to group.
User added to projectUserSent when user is added to project.
Group access expiredGroup membersSent when user’s access to a group expires in seven days. Introduced in GitLab 16.3.
Project access expiredProject membersSent when user’s access to a project expires in seven days. Introduced in GitLab 16.3.

Notifications on issues, merge requests, and epics

You also receive notifications for events happening on issues, merge requests, and epics.

Who receives notifications on issues, merge requests, and epics

In issues, merge requests, and epics, for most events, the notification is sent to:

  • Participants:
    • The author and assignee.
    • Authors of comments.
    • Anyone mentioned by username in the title or description.
    • Anyone mentioned by username in a comment if their notification level is “Participating” or higher.
  • Watchers: users with notification level “Watch”.
  • Subscribers: anyone who manually subscribed to notifications.
  • Custom: users with notification level “Custom” who turned on notifications for a fitting type of events.
note
To minimize the number of notifications that do not require any action, in GitLab 12.9 and later, eligible approvers are no longer notified for all the activities in their projects. To turn on such notifications, they have to change their user notification settings to Watch instead.

Edit notification settings for issues, merge requests, and epics

To toggle notifications on an issue, merge request, or epic: on the right sidebar, turn on or off the Notifications toggle.

When you turn on notifications, you start receiving notifications on each update, even if you haven’t participated in the discussion. When you turn notifications on in an epic, you aren’t automatically subscribed to the issues linked to the epic.

When you turn off notifications, you stop receiving notifications for updates. 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.

If you don’t see this action on the right sidebar, your project or instance might have enabled a feature flag for moved sidebar actions.

Notification events on issues, merge requests, and epics

The following table presents the events that generate notifications for issues, merge requests, and epics:

TypeEventSent to
EpicClosedSubscribers and participants.
EpicNewAnyone mentioned by username in the description, with notification level “Mention” or higher.
EpicNew noteParticipants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level “Mention” or higher.
EpicReopenedSubscribers and participants.
IssueClosedSubscribers and participants.
IssueDueParticipants and Custom notification level with this event selected.
IssueMilestone changedSubscribers and participants.
IssueMilestone removedSubscribers and participants.
IssueNewAnyone mentioned by username in the description, with notification level “Mention” or higher.
IssueNew noteParticipants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level “Mention” or higher.
IssueTitle or description changedAny new mentions by username.
IssueReassignedParticipants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee.
IssueReopenedSubscribers and participants.
Merge RequestClosedSubscribers and participants.
Merge RequestConflictAuthor and any user that has set the merge request to auto-merge.
Merge RequestMarked as readyWatchers and participants. Introduced in GitLab 13.10.
Merge RequestMergedSubscribers and participants.
Merge RequestMerged when pipeline succeedsAuthor, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. Introduced in GitLab 13.4.
Merge RequestMilestone changedSubscribers and participants.
Merge RequestMilestone removedSubscribers and participants.
Merge RequestNewAnyone mentioned by username in the description, with notification level “Mention” or higher.
Merge RequestNew noteParticipants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level “Mention” or higher.
Merge RequestPushedParticipants and Custom notification level with this event selected.
Merge RequestReassignedParticipants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee.
Merge RequestReview requestedParticipants, Watchers, Subscribers, Custom notification level with this event selected, and the old reviewer.
Merge RequestReopenedSubscribers and participants.
Merge RequestTitle or description changedAny new mentions by username.
PipelineFailedThe author of the pipeline.
PipelineFixedThe author of the pipeline. Enabled by default. Introduced in GitLab 13.1.
PipelineSuccessfulThe author of the pipeline, with Custom notification level for successful pipelines. If the pipeline failed previously, a “Fixed pipeline” message is sent for the first successful pipeline after the failure, and then a “Successful pipeline” message for any further successful pipelines.

By default, you don’t receive notifications for issues, merge requests, or epics created by yourself. To always receive notifications on your own issues, merge requests, and so on, turn on notifications about your own activity.

Notifications for unknown sign-ins

Version history
  • Introduced in GitLab 13.0.
  • Listing the full name and username of the signed-in user introduced in GitLab 15.10.
note
This feature is enabled by default for self-managed instances. Administrators may disable this feature through the Sign-in restrictions section of the UI. The feature is always enabled on GitLab.com.

When a user successfully signs in from a previously unknown IP address or device, GitLab notifies the user by email. In this way, GitLab proactively alerts users of potentially malicious or unauthorized sign-ins. This notification email includes the:

  • Hostname.
  • User’s name and username.
  • IP address.
  • Date and time of sign-in.

GitLab uses several methods to identify a known sign-in. All methods must fail for a notification email to be sent.

  • Last sign-in IP: The current sign-in IP address is checked against the last sign-in IP address.
  • Current active sessions: If the user has an existing active session from the same IP address. See Active Sessions.
  • Cookie: After successful sign in, an encrypted cookie is stored in the browser. This cookie is set to expire 14 days after the last successful sign in.

Notifications for attempted sign-ins using incorrect verification codes

Introduced in GitLab 15.5.

GitLab sends you an email notification if it detects an attempt to sign in to your account using a wrong two-factor authentication (2FA) code. This can help you detect that a bad actor gained access to your username and password, and is trying to brute force 2FA.

Notifications on designs

Introduced in GitLab 13.6.

Email notifications are sent to the participants when someone comments on a design.

The participants are:

  • Authors of the design (can be multiple people if different authors have uploaded different versions of the design).
  • Authors of comments on the design.
  • Anyone that is mentioned in a comment on the design.

Notifications on group or project access expiration

Introduced in GitLab 16.3.

GitLab sends an email notification if a user’s access to a group or project expires in seven days. This reminds group or project members to extend their access duration if they want to.

Opt out of all GitLab emails

If you no longer wish to receive any email notifications:

  1. On the left sidebar, select your avatar.
  2. Select Preferences.
  3. On the left sidebar, select Notifications.
  4. Clear the Receive product marketing emails checkbox.
  5. Set your Global notification level to Disabled.
  6. Clear the Receive notifications about your own activity checkbox.
  7. If you belong to any groups or projects, set their notification setting to Global or Disabled.

On self-managed installations, even after doing this, your instance administrator can still email you. To unsubscribe, select the unsubscribe link in one of these emails.

Email headers you can use to filter email

Notification email messages include GitLab-specific headers. To better manage your notifications, you can filter the notification emails based on the content of these headers.

For example, you could filter all emails from a specific project where you are being assigned a a merge request or an issue.

The following table lists all GitLab-specific email headers:

HeaderDescription
List-IdThe path of the project in an RFC 2919 mailing list identifier. You can use it for email organization with filters.
X-GitLab-(Resource)-IDThe ID of the resource the notification is for. The resource, for example, can be Issue, MergeRequest, Commit, or another such resource.
X-GitLab-(Resource)-StateThe state of the resource the notification is for. The resource can be, for example, Issue or MergeRequest. The value can be opened, closed, merged, or locked. Introduced in GitLab 16.4.
X-GitLab-ConfidentialIssueThe boolean value indicating issue confidentiality for notifications. Introduced in GitLab 16.0.
X-GitLab-Discussion-IDThe ID of the thread the comment belongs to, in notification emails for comments.
X-GitLab-Group-IdThe group’s ID. Only present on notification emails for epics.
X-GitLab-Group-PathThe group’s path. Only present on notification emails for epics
X-GitLab-NotificationReasonThe reason for the notification. See possible values..
X-GitLab-Pipeline-IdThe ID of the pipeline the notification is for, in notification emails for pipelines.
X-GitLab-Project-IdThe project’s ID.
X-GitLab-Project-PathThe project’s path.
X-GitLab-ProjectThe name of the project the notification belongs to.
X-GitLab-Reply-KeyA unique token to support reply by email.

X-GitLab-NotificationReason

The X-GitLab-NotificationReason header contains the reason for the notification. The value is one of the following, in order of priority:

  • own_activity
  • assigned
  • review_requested
  • mentioned
  • subscribed

The reason for the notification is also included in the footer of the notification email. For example, an email with the reason assigned has this sentence in the footer:

You are receiving this email because you have been assigned an item on <configured GitLab hostname>.

On-call alerts notifications

An on-call alert notification email can have one of the alert’s statuses:

  • alert_triggered
  • alert_acknowledged
  • alert_resolved
  • alert_ignored

Incident escalation notifications

An incident escalation notification email can have one of the incident’s status:

  • incident_triggered
  • incident_acknowledged
  • incident_resolved
  • incident_ignored

Expanding the list of events included in the X-GitLab-NotificationReason header is tracked in issue 20689.

Troubleshooting

Pull a list of recipients for notifications

If you want to pull a list of recipients to receive notifications from a project (mainly used for troubleshooting custom notifications), in a Rails console, run sudo gitlab-rails c and be sure to update the project name:

project = Project.find_by_full_path '<project_name>'
merge_request = project.merge_requests.find_by(iid: 1)
current_user = User.first
recipients = NotificationRecipients::BuildService.build_recipients(merge_request, current_user, action: "push_to"); recipients.count
recipients.each { |notify| puts notify.user.username }

Notifications about failed pipeline that doesn’t exist

If you receive notifications (through email or Slack) regarding a failed pipeline that no longer exists, double-check to see if you have any duplicate GitLab instances that could have triggered the message.