> ## 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.

# Rootly

> Create Rootly incidents automatically from DevHelm alerts

Connect DevHelm to [Rootly](https://rootly.com) to spin up an incident automatically when an alert fires. DevHelm calls the **Rootly REST API** (`POST /v1/incidents`, JSON:API format); Rootly then runs the rest of the incident lifecycle — Slack channel creation, role assignments, timeline, and post-mortems.

## Setup

<Steps>
  <Step title="Generate a Rootly API token">
    1. In Rootly, open the **Organization** dropdown → **Organization Settings** → **API Keys**
    2. Click **Generate New API Key** and choose a scope (Global, Team, or Personal) that can create incidents
    3. Set a name and expiration, then **Create** — copy the token immediately, as it's only shown once
    4. *(Optional)* Decide which **severity slug** new incidents should use (e.g. `sev0`, `sev1`), matching the severities configured in your Rootly instance
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "Rootly" \
        --type rootly \
        --config '{"channelType":"rootly","apiKey":"rootly_xxxxxxxx","severity":"sev1"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: Rootly
          config:
            channelType: rootly
            apiKey: ${ROOTLY_API_TOKEN}
            severity: sev1 # optional
      ```
    </CodeGroup>
  </Step>

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

## Configuration

| Field      | Description                                                                           | Required |
| ---------- | ------------------------------------------------------------------------------------- | -------- |
| `apiKey`   | Rootly API token with incident creation permission (sent as a `Bearer` token)         | Yes      |
| `severity` | Severity slug override, e.g. `sev0`, `sev1`; omit to let DevHelm map its own severity | No       |

## Lifecycle behavior

DevHelm creates a Rootly incident when an alert fires. Rootly then owns the incident lifecycle from that point — Slack channel creation, role assignments, the incident timeline, and post-mortems all run inside Rootly.

If you omit `severity`, DevHelm maps its own incident severity to Rootly's default; set the slug explicitly to force every DevHelm-created incident to a specific Rootly severity.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed (HTTP 401 / 403)">
    The token lacks the incident creation scope, or it's expired/revoked. Generate a new key under **Organization Settings → API Keys** with a scope that can create incidents.
  </Accordion>

  <Accordion title="Severity not applied or rejected">
    The `severity` slug must match a severity configured in Rootly. Check **Settings → Severities** for the exact slugs (e.g. `sev1`), or omit the field to let DevHelm map severity automatically.
  </Accordion>
</AccordionGroup>