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

# Notification Policies in YAML

> Define DevHelm notification policies in YAML — match rules, priority, and escalation chain references

The `notificationPolicies` section of `devhelm.yml` controls how incidents are routed to alert channels. Each policy has match rules that filter incidents and an escalation chain that defines notification steps.

## Policy fields

| Field        | Type      | Required | Description                                                  |
| ------------ | --------- | -------- | ------------------------------------------------------------ |
| `name`       | string    | Yes      | Unique policy name                                           |
| `enabled`    | boolean   | —        | Whether the policy is active (default: `true`)               |
| `priority`   | integer   | —        | Evaluation priority (higher = evaluated first, default: `0`) |
| `matchRules` | object\[] | —        | Rules that filter which incidents trigger this policy        |
| `escalation` | object    | Yes      | Escalation chain definition                                  |

## Match rules

Match rules filter which incidents trigger the policy. If no rules are defined, the policy matches all incidents.

```yaml theme={null}
notificationPolicies:
  - name: Production Alerts
    matchRules:
      - type: monitor_tag_in
        values: [production]
      - type: region_in
        regions: [us-east, eu-west]
```

| Field          | Type      | Required | Description                                                                                                                                                                   |
| -------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | string    | Yes      | Rule type: `severity_gte`, `monitor_id_in`, `region_in`, `incident_status`, `monitor_type_in`, `service_id_in`, `resource_group_id_in`, `component_name_in`, `monitor_tag_in` |
| `value`        | string    | —        | Single match value (e.g. severity for `severity_gte`)                                                                                                                         |
| `values`       | string\[] | —        | Multiple match values (e.g. tag names for `monitor_tag_in`)                                                                                                                   |
| `monitorNames` | string\[] | —        | Monitor names for `monitor_id_in` (resolved to IDs at deploy time)                                                                                                            |
| `regions`      | string\[] | —        | Regions for `region_in`                                                                                                                                                       |

## Escalation chain

The escalation chain defines an ordered sequence of notification steps:

```yaml theme={null}
notificationPolicies:
  - name: Critical Alerts
    priority: 10
    escalation:
      steps:
        - channels: [Slack Alerts]
          delayMinutes: 0
        - channels: [PagerDuty On-Call]
          delayMinutes: 5
          requireAck: true
          repeatIntervalSeconds: 300
      onResolve: Slack Alerts
      onReopen: PagerDuty On-Call
```

### Steps

| Field                   | Type      | Required | Description                                     |
| ----------------------- | --------- | -------- | ----------------------------------------------- |
| `channels`              | string\[] | Yes      | Alert channel names to notify                   |
| `delayMinutes`          | integer   | —        | Minutes to wait before this step (default: `0`) |
| `requireAck`            | boolean   | —        | Require acknowledgement before escalating       |
| `repeatIntervalSeconds` | integer   | —        | Seconds between repeated notifications          |

### Lifecycle hooks

| Field       | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| `onResolve` | string | Channel name to notify when incident resolves |
| `onReopen`  | string | Channel name to notify when incident reopens  |

## Priority and evaluation

Policies are evaluated in **descending priority** order. The first matching policy handles the incident. Use priority to ensure specific policies (e.g., production-only) take precedence:

```yaml theme={null}
notificationPolicies:
  - name: Production Critical
    priority: 20
    matchRules:
      - type: monitor_tag_in
        values: [production]
    escalation:
      steps:
        - channels: [PagerDuty On-Call]

  - name: Default Alerts
    priority: 0
    escalation:
      steps:
        - channels: [Slack Alerts]
```

## Complete example

```yaml theme={null}
notificationPolicies:
  - name: Tiered Escalation
    enabled: true
    priority: 10
    matchRules:
      - type: monitor_tag_in
        values: [production, critical]
    escalation:
      steps:
        - channels: [Slack Alerts]
          delayMinutes: 0
        - channels: [PagerDuty On-Call]
          delayMinutes: 5
          requireAck: true
        - channels: [Ops Email]
          delayMinutes: 15
      onResolve: Slack Alerts
```

## Next steps

<CardGroup cols={2}>
  <Card title="Alert channels" icon="bell" href="/mac/yaml/alert-channels">
    Define the channels referenced in your policies.
  </Card>

  <Card title="Notification policies reference" icon="book" href="/alerting/notification-policies">
    Understanding match rules and escalation logic.
  </Card>
</CardGroup>