> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Send DevHelm incidents to GitLab Alert Management via an HTTP endpoint integration

Connect DevHelm to GitLab's built-in **Alert Management** through an HTTP endpoint integration. DevHelm POSTs each incident to the endpoint GitLab generates; alerts appear under **Operations → Alerts** and can automatically open GitLab incidents if your project is configured to do so. Works with GitLab.com and self-hosted GitLab (13.1+). The endpoint URL must use HTTPS.

## Setup

<Steps>
  <Step title="Create an HTTP endpoint integration in GitLab">
    You need at least the **Maintainer** role on the project.

    1. In your GitLab project, go to **Settings → Monitor** and expand the **Alerts** section
    2. Click **Add new integration** and select **HTTP Endpoint** as the integration type
    3. Name the integration and toggle **Active** on, then **Save integration**
    4. Open the **View credentials** tab and copy the **URL** and the **Authorization Key**

    The URL looks like `https://gitlab.com/{namespace}/{project}/prometheus/alerts/notify.json` (or the equivalent path on a self-hosted instance).
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "GitLab Alerts" \
        --type gitlab \
        --config '{"channelType":"gitlab","endpointUrl":"https://gitlab.com/your-group/your-project/prometheus/alerts/notify.json","authorizationKey":"your-gitlab-authorization-key"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: GitLab Alerts
          config:
            channelType: gitlab
            endpointUrl: ${GITLAB_ALERT_ENDPOINT_URL}
            authorizationKey: ${GITLAB_ALERT_AUTH_KEY}
      ```
    </CodeGroup>
  </Step>

  <Step title="Test the channel">
    ```bash theme={null}
    devhelm alert-channels test <channel-id>
    ```
  </Step>
</Steps>

## Configuration

| Field              | Description                                                                  | Required |
| ------------------ | ---------------------------------------------------------------------------- | -------- |
| `endpointUrl`      | HTTP endpoint URL from the GitLab alert integration's *View credentials* tab | Yes      |
| `authorizationKey` | Authorization key from the same integration                                  | Yes      |

## Lifecycle behavior

GitLab uses a **trigger-resolve** lifecycle, keyed on a per-incident fingerprint (`devhelm-<incident id>`) so repeated events about the same incident map to the same GitLab alert:

| DevHelm event     | GitLab action                                                |
| ----------------- | ------------------------------------------------------------ |
| Incident created  | Fires a new alert (`monitoring_tool: DevHelm`)               |
| Incident resolved | Sends `end_time`, so GitLab auto-resolves the matching alert |
| Incident reopened | Fires the alert again under the same fingerprint             |

If your project links the integration to incident creation, GitLab opens (and can auto-close) an incident alongside the alert.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Channel creation fails with an HTTPS error">
    The endpoint URL must start with `https://`. Copy it exactly as shown in GitLab's **View credentials** tab.
  </Accordion>

  <Accordion title="GitLab returns 401 or 403">
    The authorization key doesn't match the integration. Re-copy it from **Settings → Monitor → Alerts → (your integration) → View credentials**, and make sure you paired it with the URL from the *same* integration.
  </Accordion>

  <Accordion title="Alerts aren't appearing in GitLab">
    1. Confirm the integration's **Active** toggle is on — a disabled integration rejects deliveries
    2. Use the integration's **Send test alert** tab in GitLab to confirm the endpoint itself works, then run `devhelm alert-channels test <id>`
    3. On self-hosted GitLab, ensure the instance presents a valid SSL certificate, since DevHelm only posts over HTTPS
  </Accordion>
</AccordionGroup>