Skip to main content

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.

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

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

InputDescriptionRequiredDefault
api-tokenDevHelm API token (recommended: pass via secrets.DEVHELM_API_TOKEN)No¹—
devhelm-versionCLI version to install — exact semver (e.g. 0.6.4) or latestNolatest
api-urlDevHelm API base URLNohttps://api.devhelm.io
org-idOrganization ID (multi-org tokens only)No—
workspace-idWorkspace ID (multi-workspace tokens only)No—
verify-connectionRun devhelm auth me after setup to confirm credentials workNofalse
node-versionNode.js version to install if no Node ≥18 is detected on PATH. Set to empty string to skip auto-setup.No20
¹ 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.

​
PR preview workflow

Show a deployment plan on pull requests: 
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: 
- 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: 
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

YAML file format

Learn the devhelm.yml schema and resource sections.

Deploy workflow

Understand the validate → plan → deploy lifecycle.

Multi-environment

Configure staging vs production deploys.

Generic CI

Use the CLI in GitLab, Jenkins, and other CI systems.