Skip to main content
Deploy your monitoring configuration automatically on every push. Preview changes in pull requests and gate deploys on validation.

​
Workflow pattern

The standard CI/CD pattern for monitoring as code: 
PR opened → validate + plan → merge → deploy
  1. On PR: Run devhelm validate and devhelm plan to catch errors and preview changes
  2. On merge to main: Run devhelm deploy --yes to apply the configuration

​
Choose your tool

GitHub Actions

Official setup-devhelm action with caching, version pinning, and verification.

Generic CI

GitLab CI, Jenkins, CircleCI, Bitbucket — any system that runs npm.

Multi-environment

Deploy different configs to staging and production.

Terraform CI/CD

Terraform plan and apply in CI pipelines.

​
Key concepts

​
Validate → Plan → Deploy

StageCommandAPI callsWrites
Validatedevhelm validate devhelm.ymlNoneNone
Plandevhelm plan -f devhelm.ymlRead-onlyNone
Deploydevhelm deploy -f devhelm.yml --yesRead + writeYes

​
Exit codes for gating

Use --detailed-exitcode to make deploy decisions in CI: 
devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
Exit codeMeaningCI action
0No changesPass
10Changes pendingFlag for review or auto-deploy
1ErrorFail the build

​
Deploy locking

The CLI acquires a lock before applying changes. Only one deploy runs at a time per organization. In CI, use --lock-timeout to queue behind other deploys: 
devhelm deploy -f devhelm.yml --yes --lock-timeout 60

​
Secret management

Store DEVHELM_API_TOKEN and other sensitive values as CI secrets. Reference them in YAML with ${VAR} syntax: 
alertChannels:
  - name: Slack Alerts
    type: slack
    config:
      webhookUrl: ${SLACK_WEBHOOK_URL}

​
Next steps

Deploy workflow

Detailed validate-plan-deploy lifecycle.

Drift and locking

How drift detection and deploy locks work.