• Integrations list
• Configuration
  • Single HTTP Endpoint
  • HTTP Endpoints
    • Map fields in custom alerts
  • External Prometheus integration
• Customize the alert payload outside of GitLab
• Triggering test alerts
• Automatic grouping of identical alerts
• Recovery alerts
• Link to your Opsgenie Alerts

Integrations

GitLab can accept alerts from any source via a webhook receiver. This can be configured generically or, in GitLab versions 13.1 and greater, you can configure External Prometheus instances to use this endpoint.

Integrations list

With the Maintainer role or higher, you can view the list of configured alerts integrations by navigating to Settings > Monitor in your project’s sidebar menu, and expanding the Alerts section. The list displays the integration name, type, and status (enabled or disabled):

Configuration

GitLab can receive alerts via a HTTP endpoint that you configure, or the Prometheus integration.

Single HTTP Endpoint

Enabling the HTTP Endpoint in a GitLab projects activates it to receive alert payloads in JSON format. You can always customize the payload to your liking.

1. Sign in to GitLab as a user with maintainer permissions for a project.
2. Navigate to Settings > Monitor in your project.
3. Expand the Alerts section, and in the Select integration type dropdown menu, select HTTP Endpoint.
4. Toggle the Active alert setting. The URL and Authorization Key for the webhook configuration are available in the View credentials tab after you save the integration. You must also input the URL and Authorization Key in your external service.

HTTP Endpoints

In GitLab Premium, you can create multiple unique HTTP endpoints to receive alerts from any external source in JSON format, and you can customize the payload.

1. Sign in to GitLab as a user with maintainer permissions for a project.
2. Navigate to Settings > Monitor in your project.
3. Expand the Alerts section.

4. For each endpoint you want to create:

   1. Click the Add new integration button.
   2. In the Select integration type dropdown menu, select HTTP Endpoint.
   3. Name the integration.
   4. Toggle the Active alert setting. The URL and Authorization Key for the webhook configuration are available in the View credentials tab after you save the integration. You must also input the URL and Authorization Key in your external service.

   5. (Optional) To map fields from your monitoring tool’s alert to GitLab fields, enter a sample payload and click Parse payload for custom mapping. Valid JSON is required. If you update a sample payload, you must also remap the fields.

   6. (Optional) If you provided a valid sample payload, select each value in Payload alert key to map to a GitLab alert key.
   7. To save your integration, click Save Integration. If desired, you can send a test alert from your integration’s Send test alert tab after the integration is created.

The new HTTP Endpoint displays in the integrations list. You can edit the integration by selecting the settings icon on the right side of the integrations list.

Map fields in custom alerts

You can integrate your monitoring tool’s alert format with GitLab alerts. To show the correct information in the Alert list and the Alert Details page, map your alert’s fields to GitLab fields when you create an HTTP endpoint:

External Prometheus integration

For GitLab versions 13.1 and greater, read External Prometheus Instances to configure alerts for this integration.

Customize the alert payload outside of GitLab

For HTTP Endpoints without custom mappings, you can customize the payload by sending the following parameters. All fields are optional. If the incoming alert does not contain a value for the Title field, a default value of New: Alert will be applied.

You can also add custom fields to the alert’s payload. The values of extra parameters aren’t limited to primitive types (such as strings or numbers), but can be a nested JSON object. For example:

{ "foo": { "bar": { "baz": 42 } } }

Example request:

curl --request POST \
  --data '{"title": "Incident title"}' \
  --header "Authorization: Bearer <authorization_key>" \
  --header "Content-Type: application/json" \
  <url>

The <authorization_key> and <url> values can be found when configuring an alert integration.

Example payload:

{
  "title": "Incident title",
  "description": "Short description of the incident",
  "start_time": "2019-09-12T06:00:55Z",
  "service": "service affected",
  "monitoring_tool": "value",
  "hosts": "value",
  "severity": "high",
  "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
  "foo": {
    "bar": {
      "baz": 42
    }
  }
}

Triggering test alerts

After a project maintainer or owner configures an integration, you can trigger a test alert to confirm your integration works properly.

1. Sign in as a user with Developer or greater permissions.
2. Navigate to Settings > Monitor in your project.
3. Click Alerts to expand the section.
4. Click the settings icon on the right side of the integration in the list.
5. Select the Send test alert tab to open it.
6. Enter a test payload in the payload field (valid JSON is required).
7. Click Send.

GitLab displays an error or success message, depending on the outcome of your test.

Automatic grouping of identical alerts

In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload. When an incoming alert contains the same payload as another alert (excluding the start_time and hosts attributes), GitLab groups these alerts together and displays a counter on the Alert Management List and details pages.

If the existing alert is already resolved, GitLab creates a new alert instead.

Recovery alerts

The alert in GitLab will be automatically resolved when an HTTP Endpoint receives a payload with the end time of the alert set. For HTTP Endpoints without custom mappings, the expected field is end_time. With custom mappings, you can select the expected field.

You can also configure the associated incident to be closed automatically when the alert resolves.

Link to your Opsgenie Alerts

You can monitor alerts using a GitLab integration with Opsgenie.

If you enable the Opsgenie integration, you can’t have other GitLab alert services active at the same time.

To enable Opsgenie integration:

1. Sign in as a user with the Maintainer or Owner role.
2. Navigate to Monitor > Alerts.
3. In the Integrations select box, select Opsgenie.
4. Select the Active toggle.
5. In the API URL field, enter the base URL for your Opsgenie integration, such as https://app.opsgenie.com/alert/list.
6. Select Save changes.

After you enable the integration, navigate to the Alerts list page at Monitor > Alerts, and then select View alerts in Opsgenie.