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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.