Notification emails

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• 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 GitLab Self-Managed in GitLab 15.0.
• Enhanced email styling generally available in GitLab 18.3. Feature flag enhanced_notify_css removed.
• Product marketing emails removed in GitLab 16.6.

{{< /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.

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 your username.
• 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.

GitLab does not send a notification when:

• The account is a project bot.
• The account is a service account with default email address.
• The account is blocked (banned) or deactivated.
• An administrator has blocked notifications.

Global notification settings

Your global notification settings are the default settings, unless you specify different settings for a project or a group. 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.

Edit notification settings

To edit your notification settings:

1. In the upper-right corner, select your avatar.
2. Select Preferences.
3. In the left sidebar, select Notifications.
4. In Global notification email, enter the email address your notifications are sent to. Defaults to your primary email address.
5. For Global notification level, select the default notification level to apply to your notifications.
6. Select the Receive notifications about your own activity checkbox to receive notifications about your own activity. Not selected by default.

Notification levels

To the right of each project and group you can select a notification level:

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.

When you set the notification level to Global for a project or subgroup, it does not directly inherit your global notification settings. Instead, it goes up the hierarchy and inherits the next non-global notification level that is configured, in the following order:

1. The project setting.
2. The parent group setting.
3. The ancestor groups' settings (going up the hierarchy).
4. The global notification setting as the final fallback setting.

For example, you set your default global notification setting to Watch, and your group and project notification levels as follows:

%%{init: { "fontFamily": "GitLab Sans", 'theme':'neutral' }}%%
flowchart TD
  accTitle: Notification hierarchy
  accDescr: Example of a group, subgroup, and project

    N[Default/global notification level set to Watch]
    N --> A
    A[Group A: Notification level set to Global]
    A-. Inherits Watch level .-> N
    A --> B[Subgroup B: Notification level set to Participate]
    B --> C[Project C: Notification level set to Global]
    C-. Inherits Participate level .-> B

Project C inherits the Participate notification level from subgroup B. It does not inherit the Watch notification level from your global notification settings.

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. In the upper-right corner, select your avatar.
2. Select Preferences.
3. In the left sidebar, select Notifications.
4. Locate the group in the Groups section.
5. Select the desired notification level.

Or:

1. In the top bar, select Search or go to and find your group.
2. Select the notification dropdown list, next to the bell icon ({{< icon name="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. In the upper-right corner, select your avatar.
2. Select Preferences.
3. In 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. In the upper-right corner, select your avatar.
2. Select Preferences.
3. In the left sidebar, select Notifications.
4. Locate the project in the Projects section.
5. Select the desired notification level.

Or:

1. In the top bar, select Search or go to and find your project.
2. Select the notification dropdown list, next to the bell icon ({{< icon name="notifications" >}}).
3. Select the desired notification level.

<i class="fa-youtube-play" aria-hidden="true"></i> To learn how to be notified when a new release is available, watch Notification for releases.

Notification events

Notifications are sent for user, project, or group events, and for activity on work items.

User events

{{< history >}}

• Notification for personal access token rotated introduced in GitLab 18.3.

{{< /history >}}

User notification events:

Project events

{{< history >}}

• Notification for project access expired introduced in GitLab 16.3.
• Notification for project access tokens expiring soon introduced in GitLab 16.4.
• Notification for project deploy tokens expiring soon introduced in GitLab 18.3.
• Notification for project scheduled for deletion introduced in GitLab 17.11.

{{< /history >}}

Project notification events:

Group events

{{< history >}}

• Notification for group access expired introduced in GitLab 16.3.
• Notification for group access tokens expiring soon introduced in GitLab 16.4.
• Notification for group scheduled for deletion introduced in GitLab 17.11.

{{< /history >}}

Group notification events:

Issue, merge request, and epic events

{{< history >}}

• Notifications for merge requests you're eligible to approve introduced in GitLab 16.7 and renamed in GitLab 17.11.
• Service account pipeline notifications introduced in GitLab 18.1.

{{< /history >}}

Events generate notifications based on the notification level selected. Some notifications can be optionally enabled by selecting the Custom notification level, and selecting the desired events. You can also manually subscribe to notifications for and epic, issue, or merge request.

By default, you don't receive notifications for issues, merge requests, or epics you create. You can turn on notifications about your own activity.

Epic event notifications are sent for the following notification levels:

Issue event notifications are sent for the following notification levels:

Merge request notifications are sent for the following notification levels:

Subscribe to notifications for a specific issue, merge request, or epic

To toggle notifications on a specific issue, merge request, or epic:

1. At the top of the right sidebar, select:
   • Notifications on ({{< icon name="notifications" >}}) to enable notifications.
   • Notifications off ({{< icon name="notifications-off" >}}) to disable notifications.

Moved notifications

{{< details >}}

• Offering: GitLab Self-Managed

{{< /details >}}

{{< history >}}

• Introduced in GitLab 16.5 with a flag named notifications_todos_buttons. Disabled by default.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. Enabling this feature flag moves the notifications and to-do item buttons to the upper-right corner of the page.

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.

CI/CD pipeline events

CI/CD pipeline event notifications are sent to the pipeline creator for the following notification levels:

Service account pipeline event notifications are sent for the following notification levels:

Issue 501083 tracks adding all events to the Watch level.

Disable specific events

To disable always sent security emails on GitLab Self-Managed and GitLab Dedicated, an instance administrator can disable individual background jobs.

For example:

• personal_access_tokens_expiring_worker
• personal_access_tokens_expired_notification_worker
• ssh_keys_expiring_soon_notification_worker
• ssh_keys_expired_notification_worker
• send_recurring_notifications_worker
• deploy_tokens_expiring_worker
• members_expiring_worker

Notifications for unknown sign-ins

{{< history >}}

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

{{< /history >}}

[!note] This feature is enabled by default for GitLab 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

{{< history >}}

• Introduced in GitLab 15.5.

{{< /history >}}

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

{{< history >}}

• Introduced in GitLab 16.3.

{{< /history >}}

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. In the upper-right corner, select your avatar.
2. Select Preferences.
3. In 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 GitLab Self-Managed and Dedicated instances, even after doing this, certain event notifications are still sent:

• Your instance administrator can still email you
• Notification events that are always sent

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][email protected]>
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.

Unsubscribing by email is subject to the same two year retention policy as replying by email.

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, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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 is verified in GitLab and 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.