Skip to main content
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

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

InputRequiredDefaultDescription
api-tokenNo—DevHelm API token (recommended: pass via secrets.DEVHELM_API_TOKEN)
devhelm-versionNolatestCLI version to install — exact semver (e.g., 0.1.4) or latest
api-urlNohttps://api.devhelm.ioDevHelm API base URL
org-idNo—Organization ID for multi-org accounts
verify-connectionNofalseRun devhelm auth me after setup to verify credentials
node-versionNo20Node.js version if actions/setup-node wasn’t called before

​
Action outputs

OutputDescription
devhelm-versionInstalled CLI version (e.g., 0.1.4)
cache-hitWhether the npm cache was restored

​
PR preview workflow

Show what would change before merging: 
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: 
      - name: Check for drift
        run: devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
Exit codeMeaning
0No changes needed
10Changes pending (valid config, would apply changes)
1Error (invalid config or API failure)

​
Pin the CLI version

For reproducible builds, pin the CLI version: 
      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN }}
          devhelm-version: '0.2.0'
The action caches the npm install between runs for faster execution.

​
Multi-environment deploys

Use GitHub Environments with environment-specific secrets: 
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 for file structure guidance.

​
Maintenance windows in CI

Suppress alerts during deployments: 
      - name: Create maintenance window
        run: |
          devhelm maintenance-windows create \
            --starts-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
            --ends-at "$(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

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.
Another deploy is running. Deploy locks prevent concurrent deploys per organization. Wait or force unlock:
devhelm deploy force-unlock --yes
Verify the secret is set at the repository level (Settings → Secrets and variables → Actions). Environment-level secrets need the environment: key in the job.

​
Next steps

Generic CI/CD

Use the CLI in non-GitHub CI systems.

Monitoring as Code tutorial

Full YAML format and deploy workflow.

CI/CD pipeline guide

End-to-end CI/CD setup guide.