Notifications

Structure

Though guidelines are still being defined for both email and UI notifications, you can view examples of all emails, organized by type, in either GDK or in Figma. Examples of current UI notifications are also visible in Figma. Components for both are forthcoming.

TODO:

Add structure image for email and UI notifications. Create an issue

Guidelines

Notifications from GitLab appear in two places: in a user's email and in the product, on the To-Do List. The To-Do List items are currently a small, actionable subset of the available notifications.

When to use

• When a user needs to be made aware of a system action.
• When another user is awaiting a response.
• When there is an important product update a user should be aware of.

When not to use

• Sharing trivial details. Overburdening users with notifications is fatiguing and inhibits productivity, but also devalues the notification system as a whole.
• For in-context updates, consider using an alert, toast or banner instead, depending on severity and content.

Behavior

Both email notifications and UI notifications are generally linked to the events within GitLab that generated them, allowing users to quickly jump to the relevant context, and take action if needed.

Content

Both email and UI notifications aim to keep users up-to-date about things happening within GitLab. Content of email and UI notifications is currently non-identical, though we are working to bring more of a parity between them. Until then, for any new email notifications created, consider adding a corresponding To-Do, as well.

Configuration

What appears as an email or UI notification should reflect a user's preferences for how and when they are contacted. Email notification settings are configured in user settings, under /profile/notifications. In the future, users will be able to customize what appears in their To-Do List, as well.