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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.