Notification emails

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

• Enhanced email styling introduced in GitLab 14.9 with a feature flag named enhanced_notify_css. Disabled by default.
• Enhanced email styling enabled on GitLab.com in GitLab 14.9.
• Enhanced email styling enabled on self-managed in GitLab 15.0.
• Product marketing emails removed in GitLab 16.6.

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.

In GitLab 17.2 and later, notifications are rate limited per 24 hours per project or group per user.

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:

• You participate in an issue, merge request, epic, or design. You become a participant when you comment or edit, or someone mentions ¹ you.
• You've enabled notifications in an issue, merge request, or epic.
• You've configured notifications for the project or group.
• You're subscribed to group or project pipeline notifications through the pipeline emails integration.

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:

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.
• 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 group 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 ({notifications}).
3. Select the desired notification level.

Change email address used for group notifications

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 group 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 ({notifications}).
3. Select the desired notification level.

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

Notification events

Users are notified of the following events:

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.

To minimize the number of notifications that do not require any action, eligible approvers are not 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 ({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.

Notification events on issues, merge requests, and epics

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

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

• Listing the full name and username of the signed-in user introduced in GitLab 15.10.
• Geographic location added in GitLab 17.5.

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.
• Geographic location.
• 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

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. Set your Global notification level to Disabled.
5. Clear the Receive notifications about your own activity checkbox.
6. 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.

Unsubscribe from notification emails

You can unsubscribe from notification emails from GitLab on a per-resource basis (for example a specific issue).

Using the unsubscribe link

Every notification email from GitLab contains an unsubscribe link at the bottom.

To unsubscribe:

1. Select the unsubscribe link in the email.
2. If you are signed in to GitLab in your browser, you are unsubscribed immediately.
3. If you are not signed in, you need to confirm the action.

Using an email client or other software

Your email client might show an Unsubscribe button when you view an email from GitLab. To unsubscribe, select this button.

Notification emails from GitLab contain special headers. These headers allow supported email clients and other software to unsubscribe users automatically. Here's an example:

List-Unsubscribe: <https://gitlab.com/-/sent_notifications/[REDACTED]/unsubscribe>,<mailto:incoming+[REDACTED]-unsubscribe@incoming.gitlab.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The List-Unsubscribe header has two entries:

• A link for software to send a POST request. This action directly unsubscribes the user from the resource. Sending a GET request to this link shows a confirmation dialog instead of unsubscribing.
• An email address for software to send an unsubscribe email. The content of the email is ignored.

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 merge request or an issue.

The following table lists all GitLab-specific email headers:

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

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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.

Email notifications are enabled, but not received

If you've enabled email notifications in GitLab, but users aren't receiving notifications as expected, ensure that your email provider isn't blocking emails from your GitLab instance. Many email providers (like Outlook) block emails coming from lesser-known self-managed mail server IP addresses. To verify, attempt to send an email directly from the SMTP server for your instance. For example, a test email from Sendmail might look something like:

# (echo subject: test; echo) | $(which sendmail) -v -Am -i <valid email address>

If your email provider is blocking the message, you might get output like the following (depending on your email provider and SMTP server):

Diagnostic-Code: smtp; 550 5.7.1 Unfortunately, messages from [xx.xx.xx.xx]
weren't sent. For more information, please go to
http://go.microsoft.com/fwlink/?LinkID=526655 (http://go.microsoft.com/fwlink/?LinkID=526655) AS(900)

Usually this issue can be resolved by adding the IP address of your SMTP server to your mail provider's allowlist. Check your mail provider's documentation for instructions.