> ## 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.
# Terraform Provider
> Manage DevHelm monitors, alert channels, status pages, and more as Terraform resources
The DevHelm Terraform provider lets you manage your monitoring stack — monitors, alert channels, status pages, secrets, and more — declaratively alongside your cloud infrastructure.
The provider is published on the [Terraform Registry](https://registry.terraform.io/providers/devhelmhq/devhelm/latest) as `devhelmhq/devhelm`.
**Status: Beta.** The schema is stable, the resource set is feature-complete against the DevHelm v1 API, and the provider has been validated end-to-end against production. While the other DevHelm surfaces (CLI, SDKs, MCP server) are now at `1.0.0`, the Terraform provider is intentionally held at `0.2.0-beta.x` for a short soak window to harden a defense-in-depth rollback path. Safe for production use; pin the exact version below.
## Install
```hcl theme={null}
terraform {
required_version = ">= 1.5.0"
required_providers {
devhelm = {
source = "devhelmhq/devhelm"
version = "0.2.0-beta.7"
}
}
}
provider "devhelm" {}
```
**Pre-release pin required.** The provider currently ships only as pre-release versions, and Terraform's `~>` operator never selects pre-releases. Pin the exact version above (`0.2.0-beta.7` is the latest published tag); bump it explicitly when the next version ships, or wait for the GA `1.0.0` cut to switch to a range like `~> 1.0`. Latest version is on the [Registry overview page](https://registry.terraform.io/providers/devhelmhq/devhelm/latest).
All four provider attributes have environment-variable equivalents and are optional. The most common pattern is to leave the provider block empty and supply credentials through the environment so the same config works locally, in CI, and in Terraform Cloud.
| Attribute | Env var | Default | Description |
| -------------- | ---------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `token` | `DEVHELM_API_TOKEN` | — | Required. Create under **Settings → API Keys** in the [Dashboard](https://app.devhelm.io). Sensitive. |
| `base_url` | `DEVHELM_API_URL` | `https://api.devhelm.io` | API endpoint |
| `org_id` | `DEVHELM_ORG_ID` | `1` | Organization ID (multi-org tokens only) |
| `workspace_id` | `DEVHELM_WORKSPACE_ID` | `1` | Workspace ID (multi-workspace tokens only) |
## Available resources
| Resource | Purpose |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `devhelm_monitor` | HTTP, DNS, TCP, ICMP, Heartbeat, MCP Server monitors |
| `devhelm_alert_channel` | 20 channel types: Slack, Email, PagerDuty, OpsGenie, Discord, Teams, Webhook, Telegram, Google Chat, Pushover, Mattermost, Splunk On-Call, Pushbullet, Linear, Incident.io, Rootly, Zapier, Datadog, Jira, GitLab |
| `devhelm_notification_policy` | Routing rules from monitors → channels |
| `devhelm_webhook` | Outbound webhook subscriptions for platform events |
| `devhelm_secret` | Vault secrets referenced by monitor `auth` and config |
| `devhelm_environment` | Per-environment variable scopes (production, staging, …) |
| `devhelm_tag` | Tags for filtering and grouping |
| `devhelm_resource_group` | Service / team groupings |
| `devhelm_resource_group_membership` | Add a user to a resource group |
| `devhelm_dependency` | Track third-party SaaS components (GitHub, Stripe, …) |
| `devhelm_status_page` | Public or private status pages |
| `devhelm_status_page_component` | Components shown on a status page |
| `devhelm_status_page_component_group` | Group components into sections |
| `devhelm_status_page_custom_domain` | Custom domain attached to a status page |
| `devhelm_status_page_custom_domain_verification` | DNS / TLS verification record |
## Available data sources
`devhelm_monitor`, `devhelm_alert_channel`, `devhelm_environment`, `devhelm_resource_group`, `devhelm_service`, `devhelm_status_page`, `devhelm_tag`. See [Data sources](/mac/terraform/data-sources).
## Quick example
```hcl theme={null}
resource "devhelm_tag" "production" {
name = "production"
color = "#10b981"
}
resource "devhelm_alert_channel" "ops_slack" {
name = "Engineering Slack"
channel_type = "slack"
webhook_url = var.slack_webhook_url
mention_text = "@channel"
}
resource "devhelm_monitor" "api_health" {
name = "API Health"
type = "HTTP"
frequency_seconds = 60
regions = ["us-east", "eu-west"]
config = jsonencode({
url = "https://api.example.com/health"
method = "GET"
verifyTls = true
})
assertions {
type = "status_code"
# `expected` is a STRING — quote even plain numeric codes. `200`
# (number) plans cleanly but apply fails with "Provider produced
# inconsistent result" because the API normalizes to "200" (string).
config = jsonencode({ expected = "200", operator = "equals" })
}
assertions {
type = "response_time"
config = jsonencode({ thresholdMs = 2000 })
severity = "warn"
}
tag_ids = [devhelm_tag.production.id]
alert_channel_ids = [devhelm_alert_channel.ops_slack.id]
}
```
`config` and `assertions[].config` are JSON strings (not HCL blocks). Use `jsonencode({...})` and **camelCase** field names — they map directly to the API wire format (`thresholdMs`, `verifyTls`, `expectedInterval`, …). The provider validates the payload against the generated schema at plan time, so unknown fields fail fast.
## Import existing resources
Every resource supports `terraform import` except `devhelm_status_page_custom_domain_verification` (a synthetic verification barrier with no server-side counterpart). Most are imported by their human-readable name or slug — a UUID is always accepted too:
```bash theme={null}
terraform import devhelm_monitor.api_health "API Health"
terraform import devhelm_alert_channel.ops_slack "Engineering Slack"
terraform import devhelm_tag.production "production"
```
See [Importing resources](/mac/terraform/importing) for the full ID table.
## When to use Terraform vs YAML
| Use case | Recommended tool |
| ------------------------------------------------------- | --------------------------------------------------- |
| Monitors managed alongside cloud infra (AWS, GCP, etc.) | Terraform provider |
| Standalone monitoring config, fast iteration | `devhelm.yml` + CLI |
| CI/CD with GitHub Action | `devhelm.yml` + `setup-devhelm` action |
| Mixed infra — some Terraform, some standalone | Use both (avoid managing the same resource in both) |
Don't manage the same resource with both Terraform and `devhelm.yml`. Pick one source of truth per resource to avoid drift and conflicts.
## Next steps
Full devhelm\_monitor resource reference.
Channel-type-specific arguments.
Import existing resources into Terraform state.
Automate Terraform plans and applies in CI.