Email Integration

Problem to solve

Many monitoring tools are capable of sending email alerts. An email integration is simple to use and easy to set-up. It provides an additional method by which users can surface alerts in the GitLab UI. Email integrations are very common in incident management tools. Here is documentation on email integrations with competing incident management platforms:

Intended Users

Further details

This work supports the direction of the Alert Management product category.

Proposal

Create an email endpoint that users can forward emails to to generate alerts. Locate the settings for this endpoint in the same place as the Alert Endpoint.

Technical details

These points can guide engineers to implement this features.

  • Create Gitlab::Email::Handler::AlertManagement::CreateAlertHandler
  • Add a new, alphanumeric authorization key email_token (SecureRandom.alphanumeric(32)) or incoming_email_token to Alerting::ProjectAlertingSetting as part of the email address. See Permissions and Security
  • Reuse Projects::Alerting::NotifyService passing email subject as title and body as description. Default severity critical is used
  • Use Alert bot as incident author

See !33785 (closed) for reference, inspiration and discussions/reviews.

Open questions / future work

The following questions we can tackle within this issue or follow-ups.

  • The "Incoming Email" supports auto-response via Email in case of an error. Should we support this?
    • If so we should improve error handling (currently just InvalidRecordError with message from service)
  • Allow GitLab Flavored Markdown via email including quick actions?
  • Use email date (Date: header) as starts_at?
  • Map email headers (Importance header etc.) to severity. See #217178 (comment 355619411)
  • Map email author (From: header) to project user. See !33785 (comment 356476733)

Design

The configuration for the email endpoint will live within a new Alerts section on Settings > Operations. Since this section will be re-worked extensively as part of #217766 (closed), a small MVC for this issue could look as follows:

Add email integration to existing integration dropdown Fields will update accordingly
Settings_page Settings_page_-_email

In order to make the email address more secure, we're also proposing that we add the authorization key to the email address, which would look something like this: incoming+gitlab-org-monitor-tanuki-inc-14986497-a965011188ba31fbabc6f6767d6788c7-alerts-@incoming.gitlab.com

What this means is that, when the auth key is reset, the email will also be reset. We should alert users to this within the confirmation modal that appears when the "reset key" button is clicked:

warning

Permissions and Security

The email integration is secured by the existing token (Authorization token). It's part of the receiver email address e.g. incoming+gitlab-org-monitor-tanuki-inc-14986497-x3hInIjKYXZxgrz0LP1CjMJTcZ2rDHql-alerts-@incoming.gitlab.com (here x3hInIjKYXZxgrz0LP1CjMJTcZ2rDHql).

Documentation

Availability & Testing

What does success look like, and how can we measure that?

What is the type of buyer?

Is this a cross-stage feature?

Links / references

Edited by Sarah Waldner