Custom Integrations

Problem to solve

As stated in the parent epic, enterprises are already invested and entrenched in a suite of monitoring tools, moreover, there are hundreds of monitoring tools in market today. These emit alerts with unique payloads differing in format and content. GitLab's Alert Management tool needs to be able to consume and aggregate alerts from any tool. Other incident management tools have invested in building and maintaining individual integrations so that they can consume proprietary alerts from all of these tools.

This is not a viable solution for GitLab because:

Our team focused on solving this problem in market is small (there are entire companies working on this)
Building integrations with a large percentage of these tools will take too long because of 1
Maintaining all of these integrations would be a lot of on-going work

To overcome these limitations, we need to create a simple repeatable process by which customers can integrate any tool with GitLab.

If we can create a service that enables users to easily translate proprietary alerts to the GitLab format so that GitLab can consume and display the alert in the UI, we can quickly catch up to other incident management tools in market.

Intended users

User experience goal

An operator can integrate any tool with the service with little to no code.

Proposal

Create a tool that parses alerts and allows users to map alert attributes to GitLab alert fields. Users can create new integrations and save them for each tool they want to integrate. Each time they create a new integration, that integration will get a new endpoint and unique auth token.

User Experience

User clicks New Integration
User imports example payload for alert
GitLab parses and displays the alert payload in a format that allows users to see each attribute individually (example: If the format of the alert is nested, GitLab should parse and display all fields in a single layer of key:value pairs - e.g. "alert.details.start_time": "2020-06-13T12:26:28Z")
User maps fields from their alert to GitLab's fields
User can add additional fields to GitLab alert and map to them
User can name the integration
User can edit the integration
User can delete the integration

FUTURE IDEA: These integrations could also be made available to the wider community.

Gitlab could start by creating a few integrations for highly used tools and documenting these examples.

Designs

The full flow is visible in Figma. There is also a prototype available to show how the different integration types would work.

The designs account for all the existing functionality (REST endpoint, Prometheus and Opsgenie integrations) and planned updates (email integration). In addition, they include the new "custom" workflow: