> ## 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 from GitHub Actions with the setup-devhelm action

The `devhelmhq/setup-devhelm` GitHub Action installs the DevHelm CLI and configures authentication in your CI pipeline. Use it to validate, plan, and deploy your monitoring configuration on every push.

## Quick start

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

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

## Action inputs

| Input               | Required | Default                  | Description                                                           |
| ------------------- | -------- | ------------------------ | --------------------------------------------------------------------- |
| `api-token`         | No       | —                        | DevHelm API token (recommended: pass via `secrets.DEVHELM_API_TOKEN`) |
| `devhelm-version`   | No       | `latest`                 | CLI version to install — exact semver (e.g., `0.1.4`) or `latest`     |
| `api-url`           | No       | `https://api.devhelm.io` | DevHelm API base URL                                                  |
| `org-id`            | No       | —                        | Organization ID for multi-org accounts                                |
| `verify-connection` | No       | `false`                  | Run `devhelm auth me` after setup to verify credentials               |
| `node-version`      | No       | `20`                     | Node.js version if `actions/setup-node` wasn't called before          |

## Action outputs

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

## PR preview workflow

Show what would change before merging:

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

The plan output shows resources to create, update, and delete. Review it in the Actions log before merging.

## Gate merges with dry-run

Use `--dry-run --detailed-exitcode` as a required status check:

```yaml theme={null}
      - name: Check for drift
        run: devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
```

| Exit code | Meaning                                             |
| --------- | --------------------------------------------------- |
| `0`       | No changes needed                                   |
| `10`      | Changes pending (valid config, would apply changes) |
| `1`       | Error (invalid config or API failure)               |

## Pin the CLI version

For reproducible builds, pin the CLI version:

```yaml theme={null}
      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}
          devhelm-version: '1.0.0'
```

The action caches the npm install between runs for faster execution.

## Multi-environment deploys

Use GitHub Environments with environment-specific secrets:

```yaml theme={null}
jobs:
  deploy-staging:
    environment: staging
    steps:
      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}
      - run: devhelm deploy -f devhelm.staging.yml --yes

  deploy-production:
    needs: deploy-staging
    environment: production
    steps:
      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}
      - run: devhelm deploy -f devhelm.yml --yes
```

See [Multi-environment config](/guides/multi-environment-config) for file structure guidance.

## Maintenance windows in CI

Suppress alerts during deployments:

```yaml theme={null}
      - name: Create maintenance window
        run: |
          devhelm maintenance-windows create \
            --start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
            --end   "$(date -u -d '+15 minutes' +%Y-%m-%dT%H:%M:%SZ)" \
            --reason "CI deployment ${{ github.sha }}"

      - name: Deploy application
        run: ./scripts/deploy.sh

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="Action fails with 'Node.js is required'">
    The action auto-installs Node.js 20 by default. If you've set `node-version: ''` to skip auto-setup, make sure `actions/setup-node` runs before `setup-devhelm`.
  </Accordion>

  <Accordion title="Deploy fails with 'lock held'">
    Another deploy is running. Deploy locks prevent concurrent deploys per organization. Wait or force unlock:

    ```bash theme={null}
    devhelm deploy force-unlock --yes
    ```
  </Accordion>

  <Accordion title="api-token not working">
    Verify the secret is set at the repository level (Settings → Secrets and variables → Actions). Environment-level secrets need the `environment:` key in the job.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Generic CI/CD" icon="rotate" href="/integrations/generic-ci">
    Use the CLI in non-GitHub CI systems.
  </Card>

  <Card title="Monitoring as Code tutorial" icon="file-code" href="/guides/monitoring-as-code">
    Full YAML format and deploy workflow.
  </Card>

  <Card title="CI/CD pipeline guide" icon="wrench" href="/guides/ci-cd-pipeline">
    End-to-end CI/CD setup guide.
  </Card>
</CardGroup>