setup-devhelm

GitHub Action to install and configure the DevHelm CLI for monitoring-as-code workflows.

Usage

Basic — validate config on PRs

- uses: actions/checkout@v4
- uses: devhelmhq/setup-devhelm@v1
- run: devhelm validate

Pin a specific version

- uses: devhelmhq/setup-devhelm@v1
  with:
    devhelm-version: '0.1.4'

Authenticate and verify

- uses: devhelmhq/setup-devhelm@v1
  with:
    api-token: ${{ secrets.DEVHELM_API_TOKEN }}
    org-id: ${{ vars.DEVHELM_ORG_ID }}
    workspace-id: ${{ vars.DEVHELM_WORKSPACE_ID }}
    verify-connection: true

Full CI/CD example

name: DevHelm Monitoring as Code

on:
  push:
    branches: [main]
    paths: ['devhelm.yml']
  pull_request:
    paths: ['devhelm.yml']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: devhelmhq/setup-devhelm@v1
      - run: devhelm validate

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}
          org-id: ${{ vars.DEVHELM_ORG_ID }}
          workspace-id: ${{ vars.DEVHELM_WORKSPACE_ID }}
          verify-connection: true
      - run: devhelm deploy devhelm.yml
      - run: devhelm status --output json

Inputs

Input	Required	Default	Description
devhelm-version	No	latest	CLI version — exact semver (e.g. 0.1.4) or latest
api-token	No	—	DevHelm API token. Pass via secrets.DEVHELM_API_TOKEN
api-url	No	—	API base URL (default: https://api.devhelm.io)
org-id	No	—	Organization ID for multi-org accounts
workspace-id	No	—	Workspace ID for multi-workspace accounts
verify-connection	No	false	Run devhelm auth me after setup to verify credentials
node-version	No	20	Node.js version to install only if none is detected on PATH (or if detected version is <18). Existing Node >=18 is preserved as-is. Set to '' to skip auto-install entirely

Outputs

Output	Description
devhelm-version	Installed CLI version (e.g. 0.1.4)
cache-hit	true if the npm cache was restored

How it works

1. Node.js — detects an existing node on PATH; if it's >=18, the action keeps it and skips actions/setup-node entirely. Otherwise it installs node-version (default 20) via actions/setup-node.
2. Cache — restores ~/.npm cache keyed on OS + CLI version
3. Install — runs npm install -g devhelm@<version>
4. Environment — exports DEVHELM_API_TOKEN, DEVHELM_API_URL, DEVHELM_ORG_ID, DEVHELM_WORKSPACE_ID for all subsequent steps
5. Verify — optionally runs devhelm auth me to fail fast on bad credentials

Compatibility with caller-installed Node

If your workflow already runs actions/setup-node@v4 (or otherwise pins a Node version) before this action, your Node version is preserved. The action only installs Node when none is on PATH or the detected major is <18. You no longer need to set node-version: '' to avoid being silently downgraded.

Security

• Never hardcode tokens in workflow files. Use GitHub Secrets.
• The api-token input is passed through environment variables, never logged.
• For org/workspace IDs (non-sensitive), use GitHub Variables.

Requirements

• Node.js >= 18 — if not present (or the detected version is <18), the action installs Node 20 by default. Any pre-existing Node >=18 set up by an earlier step is left untouched. Set node-version: '' to skip the install fallback entirely (the action will then error if Node is missing).
• npm — ships with Node.js.

License

MIT — see LICENSE.