> ## 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.

# Deploy Workflow

> The DevHelm deploy lifecycle — validate, plan, deploy, and verify your monitoring configuration

The deploy workflow follows a validate-plan-deploy pattern similar to Terraform. Preview changes before applying them.

## Lifecycle

```
devhelm validate → devhelm plan → devhelm deploy
    (offline)       (read-only)     (applies changes)
```

### 1. Validate

Check YAML syntax and schema validity offline — no API calls are made:

```bash theme={null}
devhelm validate devhelm.yml
```

Validates:

* YAML syntax
* Required fields for each resource type
* Type-specific config (e.g., `url` required for HTTP monitors)
* Cross-references (e.g., alert channel names exist in config) — reported as warnings; pass `--strict` to fail on them
* Environment variable resolution — pass `--skip-env` for a syntax-only check without resolving `${VAR}` references

### 2. Plan

Preview what would change without applying anything:

```bash theme={null}
devhelm plan -f devhelm.yml
```

The plan compares your YAML against the current API state and shows resources to **create**, **update**, and **delete** (if pruning is enabled). No deploy lock is acquired and no writes are made.

### 3. Deploy

Apply the configuration:

```bash theme={null}
devhelm deploy -f devhelm.yml --yes
```

The deploy:

1. Loads and validates the YAML
2. Fetches current state from the API
3. Computes the diff (same as plan)
4. Prompts for confirmation (unless `--yes`)
5. Acquires a deploy lock (unless `--no-lock`)
6. Applies changes in dependency order
7. Releases the deploy lock and updates `.devhelm/state.json`

## Non-interactive mode

For CI pipelines, always pass `--yes` to skip the confirmation prompt:

```bash theme={null}
devhelm deploy -f devhelm.yml --yes
```

## Dry-run with exit codes

Combine `--dry-run` and `--detailed-exitcode` for CI gating:

```bash theme={null}
devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
```

| Exit code | Meaning                                             |
| --------- | --------------------------------------------------- |
| `0`       | No changes needed                                   |
| `10`      | Changes pending                                     |
| `4`       | Validation error                                    |
| `11`      | API error (including a held deploy lock)            |
| `13`      | Partial failure — some changes applied, some failed |
| `1`       | Other error                                         |

## JSON output

Get structured output for programmatic consumption:

```bash theme={null}
devhelm deploy -f devhelm.yml --dry-run -o json
```

## Pruning

By default, deploy only creates and updates resources. Resources not in your YAML are left untouched.

| Flag              | Behavior                                                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| *(default)*       | Create and update only                                                                                                                   |
| `--prune`         | Also delete resources tracked in this config's `.devhelm/state.json` that are absent from YAML (does not touch other configs' resources) |
| `--prune-org-cli` | Widen to all CLI-managed resources in the org absent from YAML                                                                           |
| `--prune-all`     | Delete all resources absent from config, including dashboard- and Terraform-managed ones                                                 |

```bash theme={null}
devhelm deploy -f devhelm.yml --prune --yes
```

<Warning>
  `--prune-all` removes resources created outside config-as-code. Review the plan carefully before using it.
</Warning>

## Multi-file deploys

Split config across files for organization:

```bash theme={null}
devhelm deploy -f monitors.yml -f alert-channels.yml --yes
```

Or point to a directory:

```bash theme={null}
devhelm deploy -f config/ --yes
```

All `*.yml` and `*.yaml` files in the directory are loaded in sorted order and their sections concatenated. Resource names must be unique across all files — duplicates are a validation error.

## Next steps

<CardGroup cols={2}>
  <Card title="Drift and locking" icon="lock" href="/mac/yaml/drift-and-locking">
    How drift detection and deploy locks work.
  </Card>

  <Card title="CI/CD patterns" icon="rotate" href="/mac/ci-cd/overview">
    Automate the deploy workflow in CI.
  </Card>
</CardGroup>