Add X-GitLab headers to an alert's email

app/mailers/emails/projects.rb

@@ -60,9 +60,32 @@ module Emails
       @project = project
       @alert = alert.present
 
+      add_project_headers
+      add_alert_headers
+
       subject_text = "Alert: #{@alert.email_title}"
       mail(to: user.notification_email_for(@project.group), subject: subject(subject_text))
     end
+
+    private
+
+    def add_alert_headers
+      return unless @alert
+
+      headers['X-GitLab-Alert-ID'] = @alert.id
+      headers['X-GitLab-Alert-IID'] = @alert.iid
+      headers['X-GitLab-NotificationReason'] = "alert_#{@alert.state}"
+
+      add_incident_headers
+    end
+
+    def add_incident_headers
+      incident = @alert.issue
+      return unless incident
+
+      headers['X-GitLab-Incident-ID'] = incident.id
+      headers['X-GitLab-Incident-IID'] = incident.iid
+    end
   end
 end
 

doc/user/profile/notifications.md

@@ -328,5 +328,12 @@ reason `assigned` has this sentence in the footer:
 
 - `You are receiving this email because you have been assigned an item on <configured GitLab hostname>.`
 
-NOTE:
 Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/20689).
+
+For example, an alert notification email can have one of
+[the alert's](../../operations/incident_management/alerts.md) statuses:
+
+- `alert_triggered`
+- `alert_acknowledged`
+- `alert_resolved`
+- `alert_ignored`

spec/mailers/emails/projects_spec.rb

@@ -36,6 +36,27 @@ RSpec.describe Emails::Projects do
       Notify.prometheus_alert_fired_email(project, user, alert)
     end
 
+    it_behaves_like 'an email with X-GitLab headers containing project details'
+
+    it 'has expected X-GitLab alert headers', :aggregate_failures do
+      is_expected.to have_header('X-GitLab-Alert-ID', /#{alert.id}/)
+      is_expected.to have_header('X-GitLab-Alert-IID', /#{alert.iid}/)
+      is_expected.to have_header('X-GitLab-NotificationReason', "alert_#{alert.state}")
+
+      is_expected.not_to have_header('X-GitLab-Incident-ID', /.+/)
+      is_expected.not_to have_header('X-GitLab-Incident-IID', /.+/)
+    end
+
+    context 'with incident' do
+      let(:alert) { create(:alert_management_alert, :with_issue, :from_payload, payload: payload, project: project) }
+      let(:incident) { alert.issue }
+
+      it 'has expected X-GitLab incident headers', :aggregate_failures do
+        is_expected.to have_header('X-GitLab-Incident-ID', /#{incident.id}/)
+        is_expected.to have_header('X-GitLab-Incident-IID', /#{incident.iid}/)
+      end
+    end
+
     context 'with empty payload' do
       let(:payload) { {} }