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)
) orincoming_email_token
toAlerting::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 severitycritical
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)
- If so we should improve error handling (currently just
- Allow GitLab Flavored Markdown via email including quick actions?
- Use email date (
Date:
header) asstarts_at
? - Map email headers (
Importance
header etc.) toseverity
. 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 |
---|---|
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:
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
).