Monitoring as Code Tutorial

By the end of this guide, you’ll have a complete devhelm.yml defining monitors, alert channels, and tags — deployed via the CLI.

Prerequisites

DevHelm CLI installed (npm install -g devhelm)
An API token set as DEVHELM_API_TOKEN
A text editor

File format

A devhelm.yml file has a version field and one or more resource sections:

version: "1"

tags:
  - name: production
    color: "#10b981"

monitors:
  - name: API Health
    type: HTTP
    config:
      url: https://api.example.com/health
      method: GET
    frequencySeconds: 60
    regions:
      - us-east
      - eu-west
    tags:
      - production

alertChannels:
  - name: Engineering Slack
    config:
      channelType: slack
      webhookUrl: ${SLACK_WEBHOOK_URL}

Secret references

Use ${VAR_NAME} syntax to reference environment variables or DevHelm secrets. Secrets are resolved at deploy time — never store credentials in the YAML file.

alertChannels:
  - name: PagerDuty On-Call
    config:
      channelType: pagerduty
      routingKey: ${PAGERDUTY_ROUTING_KEY}

Set secrets via the CLI or environment variables:

devhelm secrets create --key SLACK_WEBHOOK_URL --value https://hooks.slack.com/...
devhelm secrets create --key PAGERDUTY_ROUTING_KEY --value your-routing-key

CLI workflow

Validate

Check config syntax offline (no API calls):

devhelm validate devhelm.yml

Validation runs against the DevHelm JSON Schema. Editors with JSON Schema support (VS Code, JetBrains) provide autocomplete and inline validation.

Plan

Preview what would change without applying:

devhelm plan -f devhelm.yml

Plan output shows resources to create, update, and delete. Use -o json for machine-readable output:

devhelm plan -f devhelm.yml -o json

Deploy

Apply changes:

devhelm deploy -f devhelm.yml

Deploy shows the plan and asks for confirmation. Use --yes to skip confirmation (for CI):

devhelm deploy -f devhelm.yml --yes

Use --dry-run to simulate without applying:

devhelm deploy -f devhelm.yml --dry-run

With --detailed-exitcode, dry-run returns exit code 10 when changes are pending (useful for CI gating):

devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode

CI/CD integration

GitHub Actions

name: Deploy Monitoring Config
on:
  push:
    branches: [main]
    paths: ['devhelm.yml']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}

      - name: Validate
        run: devhelm validate devhelm.yml

      - name: Deploy
        run: devhelm deploy -f devhelm.yml --yes

PR preview

Add a plan step to pull requests to preview changes before merging:

name: Monitor Config Preview
on:
  pull_request:
    paths: ['devhelm.yml']

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}

      - name: Plan
        run: devhelm plan -f devhelm.yml

Deploy locking

DevHelm uses deploy locks to prevent concurrent deploys from conflicting. Only one deploy can run at a time per organization. If a deploy is interrupted, you can release the lock:

devhelm deploy force-unlock --yes

Drift detection

If someone modifies a resource through the Dashboard while you’re managing it via Monitoring as Code, devhelm plan shows the drift. The next devhelm deploy overwrites the Dashboard changes with the YAML definition — YAML is the source of truth.

Next steps

YAML file format

Full schema reference for devhelm.yml.

CI/CD pipeline guide

Set up automated deploys from GitHub Actions.

Terraform provider

Alternative: manage monitors with Terraform.

Deploy workflow

Deep dive into validate → plan → deploy.

Overview

Getting Started

Monitoring Guides

Alerting Guides

Incident Guides

Status Data Guides

Monitoring as Code Guides

Monitoring as Code Tutorial

File format

Secret references

CLI workflow

Validate

Plan

Deploy

CI/CD integration

GitHub Actions

PR preview

Deploy locking

Drift detection

Next steps

YAML file format

CI/CD pipeline guide

Terraform provider

Deploy workflow

​File format

​Secret references

​CLI workflow

​Validate

​Plan

​Deploy

​CI/CD integration

​GitHub Actions

​PR preview

​Deploy locking

​Drift detection

​Next steps

YAML file format

CI/CD pipeline guide

Terraform provider

Deploy workflow

File format

Secret references

CLI workflow

Validate

Plan

Deploy

CI/CD integration

GitHub Actions

PR preview

Deploy locking

Drift detection

Next steps