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


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