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

# GitHub Actions

> Deploy DevHelm monitoring config with the setup-devhelm GitHub Action — validate, plan, and deploy in CI

The `devhelmhq/setup-devhelm` GitHub Action installs the DevHelm CLI and authenticates it in your workflow. Use it to validate, test, and deploy monitoring configurations as part of your CI/CD pipeline.

## Basic usage

```yaml theme={null}
name: Deploy Monitoring
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 config
        run: devhelm validate devhelm.yml

      - name: Deploy
        run: devhelm deploy -f devhelm.yml --yes
```

## Inputs

| Input               | Description                                                                                                | Required | Default                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------------------------ |
| `api-token`         | DevHelm API token (recommended: pass via `secrets.DEVHELM_API_TOKEN`)                                      | No¹      | —                        |
| `devhelm-version`   | CLI version to install — exact semver (e.g. `0.6.4`) or `latest`                                           | No       | `latest`                 |
| `api-url`           | DevHelm API base URL                                                                                       | No       | `https://api.devhelm.io` |
| `org-id`            | Organization ID (multi-org tokens only)                                                                    | No       | —                        |
| `workspace-id`      | Workspace ID (multi-workspace tokens only)                                                                 | No       | —                        |
| `verify-connection` | Run `devhelm auth me` after setup to confirm credentials work                                              | No       | `false`                  |
| `node-version`      | Node.js version to install **if no Node ≥18 is detected on PATH**. Set to empty string to skip auto-setup. | No       | `20`                     |

¹ `api-token` is technically optional so the action can be used to install the CLI without authenticating (e.g. `devhelm --version` smoke test). Required for any command that hits the API.

## Outputs

| Output            | Description                                       |
| ----------------- | ------------------------------------------------- |
| `devhelm-version` | Installed CLI version (semver only, e.g. `1.3.0`) |
| `cache-hit`       | Whether the npm cache was restored                |

## PR preview workflow

Show a deployment plan on pull requests:

```yaml theme={null}
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: Validate
        run: devhelm validate devhelm.yml

      - name: Plan
        run: devhelm plan -f devhelm.yml
```

## Gated deploy with dry-run

Use `--detailed-exitcode` to gate deploys based on whether changes exist:

```yaml theme={null}
- name: Check for changes
  id: dryrun
  run: devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
  continue-on-error: true

- name: Deploy (if changes)
  if: steps.dryrun.outcome == 'failure'
  run: devhelm deploy -f devhelm.yml --yes
```

Exit code `10` means changes are pending; exit code `0` means no changes.

## Multi-environment setup

Deploy different configs per environment using matrix or branch conditions:

```yaml theme={null}
jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env: [staging, production]
    steps:
      - uses: actions/checkout@v4

      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets[format('DEVHELM_TOKEN_{0}', matrix.env)] }}

      - run: devhelm deploy -f devhelm.${{ matrix.env }}.yml --yes
```

## Secrets setup

1. Go to your GitHub repository → **Settings** → **Secrets and variables** → **Actions**
2. Add `DEVHELM_API_TOKEN` with your DevHelm API key
3. For multi-environment setups, add per-environment tokens (e.g., `DEVHELM_TOKEN_STAGING`, `DEVHELM_TOKEN_PRODUCTION`)

## Next steps

<CardGroup cols={2}>
  <Card title="YAML file format" icon="file-code" href="/mac/yaml/file-format">
    Learn the devhelm.yml schema and resource sections.
  </Card>

  <Card title="Deploy workflow" icon="rocket" href="/mac/yaml/workflow">
    Understand the validate → plan → deploy lifecycle.
  </Card>

  <Card title="Multi-environment" icon="layer-group" href="/mac/ci-cd/multi-environment">
    Configure staging vs production deploys.
  </Card>

  <Card title="Generic CI" icon="rotate" href="/mac/ci-cd/generic">
    Use the CLI in GitLab, Jenkins, and other CI systems.
  </Card>
</CardGroup>