Skip to main content
By the end of this guide, you’ll have a complete devhelm.yml defining monitors, alert channels, and tags — deployed via the CLI.
  • 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
    frequencySeconds: 60
    regions:
      - us-east
      - eu-west
    tags:
      - production

alert-channels:
  - name: Engineering Slack
    type: SLACK
    config:
      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. 
alert-channels:
  - name: PagerDuty On-Call
    type: PAGERDUTY
    config:
      routingKey: ${PAGERDUTY_ROUTING_KEY}
Set secrets via the CLI or environment variables: 
devhelm secrets set SLACK_WEBHOOK_URL=https://hooks.slack.com/...
devhelm secrets set PAGERDUTY_ROUTING_KEY=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.