Skip to main content
DevHelm detects when resources managed by code are modified through the dashboard or API. Deploy locks prevent concurrent modifications.

​
Drift detection

Every time you run devhelm plan or devhelm deploy, the CLI:
  1. Loads your YAML configuration
  2. Fetches the current state of each resource from the API
  3. Compares the desired state (YAML) against the current state (API)
  4. Reports differences as create, update, or delete operations
The API is always the source of truth for current values — drift comparison runs against live data, never a cached copy. Separately, the CLI keeps a local state file at .devhelm/state.json that records which resources this config manages (name → API ID). It scopes --prune to this config’s resources, disambiguates renames (via moved blocks), and lets you adopt existing resources with devhelm import. Inspect it with devhelm state show, or rebuild it from the API with devhelm state pull.

​
What drift looks like

If someone changes a monitor’s frequency in the dashboard from 60 to 30, the next plan shows:
Running deploy reverts the dashboard change back to what’s defined in YAML.

​
Special handling

​
Deploy locking

Only one deploy can run at a time per organization. The lock prevents race conditions when multiple CI jobs or team members deploy concurrently.

​
How locks work

  1. Before applying changes, the CLI acquires a lock via POST /api/v1/deploy/lock
  2. The lock includes the deployer identity and a 30-minute TTL
  3. After the deploy completes (or fails), the lock is released
  4. If the lock is held by another session, the CLI exits immediately with exit code 11 (unless --lock-timeout is set)

​
Waiting for a lock

Use --lock-timeout to wait instead of failing immediately:
The CLI retries every 5 seconds until the timeout expires.

​
Skipping the lock

For development or testing, skip locking entirely:
Skipping locks in shared environments can cause inconsistent state if two deploys run simultaneously.

​
Force-unlocking

If a deploy crashes without releasing its lock, force-unlock it:
Only use this when you’re certain no other deploy is running. Locks also expire automatically after 30 minutes.

​
Avoiding conflicts

​
YAML + dashboard

If your team uses both YAML config and the dashboard:
  • Resources in YAML are managed by the CLI. Dashboard changes will be overwritten on the next deploy.
  • Resources not in YAML are left untouched by default. --prune deletes only resources tracked in this config’s .devhelm/state.json; --prune-org-cli widens that to all CLI-managed resources in the org; --prune-all also deletes dashboard- and Terraform-managed resources.

​
YAML + Terraform

Don’t manage the same resource with both tools. Each resource should have a single source of truth:

​
Plan as a safety net

Always run devhelm plan before deploying to catch unexpected changes:
In CI, use --dry-run --detailed-exitcode to gate merges.

​
Next steps

Deploy workflow

The validate-plan-deploy lifecycle.

CI/CD patterns

Automate deploys and drift checks in CI.