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

# Tags and Secrets in YAML

> Define tags, reference secrets, and use environment variables in DevHelm YAML configuration

Tags, environments, secrets, webhooks, and dependencies are supporting resources you define alongside monitors and alert channels.

## Tags

Tags organize monitors for filtering and alert routing:

```yaml theme={null}
tags:
  - name: production
    color: "#10b981"
  - name: api
    color: "#3b82f6"
  - name: database
```

| Field   | Type   | Required | Description                              |
| ------- | ------ | -------- | ---------------------------------------- |
| `name`  | string | Yes      | Tag name, unique within the organization |
| `color` | string | —        | Hex color code (e.g., `#10b981`)         |

Reference tags by name in monitors:

```yaml theme={null}
monitors:
  - name: API Health
    type: HTTP
    config:
      url: https://api.example.com/health
      method: GET
    tags: [production, api]
```

## Environments

Environments represent deployment stages with variable substitution:

```yaml theme={null}
environments:
  - name: Production
    slug: production
    isDefault: true
    variables:
      BASE_URL: https://api.example.com
      TIMEOUT: "30"

  - name: Staging
    slug: staging
    variables:
      BASE_URL: https://staging-api.example.com
      TIMEOUT: "60"
```

| Field       | Type    | Required | Description                                           |
| ----------- | ------- | -------- | ----------------------------------------------------- |
| `name`      | string  | Yes      | Human-readable name                                   |
| `slug`      | string  | Yes      | URL-safe identifier (lowercase, hyphens, underscores) |
| `isDefault` | boolean | —        | Whether this is the default environment               |
| `variables` | map     | —        | Key-value pairs for variable substitution             |

Reference environments by slug in monitors:

```yaml theme={null}
monitors:
  - name: API Health
    type: HTTP
    config:
      url: https://api.example.com/health
      method: GET
    environment: production
```

## Secrets

Secrets store sensitive credentials in the DevHelm vault. Define them in YAML and reference them in monitor `auth` blocks:

```yaml theme={null}
secrets:
  - key: API_TOKEN
    value: ${API_TOKEN}
  - key: BASIC_CREDS
    value: ${BASIC_AUTH_CREDENTIALS}
```

| Field   | Type   | Required | Description                                            |
| ------- | ------ | -------- | ------------------------------------------------------ |
| `key`   | string | Yes      | Secret name (used to reference in auth blocks)         |
| `value` | string | Yes      | Secret value (use `${VAR}` to inject from environment) |

Reference secrets by key in monitor authentication:

```yaml theme={null}
monitors:
  - name: Protected API
    type: HTTP
    config:
      url: https://api.example.com/internal
      method: GET
    auth:
      type: bearer
      secret: API_TOKEN
```

<Note>
  Secret values are write-only. The CLI compares SHA-256 hashes for drift detection — actual values are never read back from the API.
</Note>

## Webhooks

Platform webhooks push events from DevHelm to your HTTP endpoints:

```yaml theme={null}
webhooks:
  - url: https://hooks.example.com/devhelm
    subscribedEvents: [monitor.created, incident.created, incident.resolved]
    description: Event forwarder
    enabled: true
```

| Field              | Type      | Required | Description                                                                                                             |
| ------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `url`              | string    | Yes      | Endpoint URL (also used as the unique identifier)                                                                       |
| `subscribedEvents` | string\[] | Yes      | Event types to subscribe to (e.g. `monitor.created`, `incident.created`, `incident.resolved`, `service.status_changed`) |
| `description`      | string    | —        | Human-readable description                                                                                              |
| `enabled`          | boolean   | —        | Whether the webhook is active (default: `true`)                                                                         |

## Dependencies

Track third-party services from the Status Data catalog:

```yaml theme={null}
dependencies:
  - service: github
    alertSensitivity: INCIDENTS_ONLY
  - service: aws-s3
    alertSensitivity: MAJOR_ONLY
    component: us-east-1
```

| Field              | Type   | Required | Description                                                                                                                                                                                                       |
| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `service`          | string | Yes      | Service slug from the catalog                                                                                                                                                                                     |
| `alertSensitivity` | string | —        | `ALL`, `INCIDENTS_ONLY`, `MAJOR_ONLY`, or `AWARENESS`. Defaults to `AWARENESS` (silent tracking — incident appears on the dashboard but no alert channels fire). Set one of the paging modes to opt in to alerts. |
| `component`        | string | —        | Specific service component to monitor                                                                                                                                                                             |

## Next steps

<CardGroup cols={2}>
  <Card title="Monitors" icon="signal" href="/mac/yaml/monitors">
    Define monitors that use tags, environments, and secrets.
  </Card>

  <Card title="File format" icon="file-code" href="/mac/yaml/file-format">
    Full YAML schema overview.
  </Card>
</CardGroup>