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

# PagerDuty

> Trigger and resolve PagerDuty incidents automatically from DevHelm monitor failures

Connect DevHelm to PagerDuty to automatically trigger and resolve incidents. DevHelm uses the **PagerDuty Events API v2**, maintaining incident state — when a DevHelm incident resolves, the corresponding PagerDuty alert resolves too.

## Setup

<Steps>
  <Step title="Get your PagerDuty routing key">
    1. In PagerDuty, go to **Services** → select your service → **Integrations**
    2. Click **Add Integration** and select **Events API v2**
    3. Copy the **Integration Key** (this is your routing key)
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "On-Call PagerDuty" \
        --type pagerduty \
        --config '{"channelType":"pagerduty","routingKey":"your-events-api-v2-routing-key"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: On-Call PagerDuty
          config:
            channelType: pagerduty
            routingKey: ${PAGERDUTY_ROUTING_KEY}
      ```
    </CodeGroup>
  </Step>

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

## Configuration

| Field              | Description                                                         | Required |
| ------------------ | ------------------------------------------------------------------- | -------- |
| `routingKey`       | PagerDuty Events API v2 routing (integration) key                   | Yes      |
| `severityOverride` | Override PagerDuty severity: `critical`, `error`, `warning`, `info` | No       |

## Lifecycle behavior

PagerDuty uses **trigger-resolve** lifecycle:

| DevHelm event     | PagerDuty action                 |
| ----------------- | -------------------------------- |
| Incident created  | Triggers a new alert             |
| Incident resolved | Resolves the corresponding alert |
| Incident reopened | Triggers a new alert             |

This keeps PagerDuty incident state in sync with DevHelm — no manual cleanup needed.

## Severity mapping

By default, DevHelm maps severities to PagerDuty:

| DevHelm severity | PagerDuty severity |
| ---------------- | ------------------ |
| DOWN             | `critical`         |
| DEGRADED         | `warning`          |

Use `severityOverride` to force all alerts to a specific PagerDuty severity regardless of the DevHelm incident severity.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Alerts not triggering">
    1. Verify the routing key is for **Events API v2** (not the REST API)
    2. Check that the PagerDuty service is enabled and has an escalation policy
    3. Run `devhelm alert-channels test <id>` to verify delivery
  </Accordion>

  <Accordion title="Alerts not auto-resolving">
    Resolution uses the same routing key. If you rotated the key in PagerDuty, update it in DevHelm too.
  </Accordion>
</AccordionGroup>