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

# CI/CD for Monitoring as Code

> Automate DevHelm monitoring deployments in CI/CD pipelines

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

<CardGroup cols={2}>
  <Card title="GitHub Actions" icon="github" href="/mac/ci-cd/github-actions">
    Official setup-devhelm action with caching, version pinning, and verification.
  </Card>

  <Card title="Generic CI" icon="gears" href="/mac/ci-cd/generic">
    GitLab CI, Jenkins, CircleCI, Bitbucket — any system that runs npm.
  </Card>

  <Card title="Multi-environment" icon="layer-group" href="/mac/ci-cd/multi-environment">
    Deploy different configs to staging and production.
  </Card>

  <Card title="Terraform CI/CD" icon="cube" href="/mac/terraform/ci-cd">
    Terraform plan and apply in CI pipelines.
  </Card>
</CardGroup>

## Key concepts

### Validate → Plan → Deploy

| Stage    | Command                               | API calls    | Writes |
| -------- | ------------------------------------- | ------------ | ------ |
| Validate | `devhelm validate devhelm.yml`        | None         | None   |
| Plan     | `devhelm plan -f devhelm.yml`         | Read-only    | None   |
| Deploy   | `devhelm deploy -f devhelm.yml --yes` | Read + write | Yes    |

### Exit codes for gating

Use `--detailed-exitcode` to make deploy decisions in CI:

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

| Exit code | Meaning          | CI action                      |
| --------- | ---------------- | ------------------------------ |
| `0`       | No changes       | Pass                           |
| `10`      | Changes pending  | Flag for review or auto-deploy |
| `4`       | Validation error | Fail the build                 |
| `11`      | API error        | Fail the build                 |
| `1`       | Other error      | Fail 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:

```bash theme={null}
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:

```yaml theme={null}
alertChannels:
  - name: Slack Alerts
    config:
      channelType: slack
      webhookUrl: ${SLACK_WEBHOOK_URL}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Deploy workflow" icon="rocket" href="/mac/yaml/workflow">
    Detailed validate-plan-deploy lifecycle.
  </Card>

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