GitHub Actions

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

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:

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

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

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

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.

Deploy fails with 'lock held'

Another deploy is running. Deploy locks prevent concurrent deploys per organization. Wait or force unlock:

devhelm deploy force-unlock --yes

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.

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.

Overview

Alert Channels

CI/CD

Quick start

Action inputs

Action outputs

PR preview workflow

Gate merges with dry-run

Pin the CLI version

Multi-environment deploys

Maintenance windows in CI

Troubleshooting

Next steps

Generic CI/CD

Monitoring as Code tutorial

CI/CD pipeline guide

​Quick start

​Action inputs

​Action outputs

​PR preview workflow

​Gate merges with dry-run

​Pin the CLI version

​Multi-environment deploys

​Maintenance windows in CI

​Troubleshooting

​Next steps

Generic CI/CD

Monitoring as Code tutorial

CI/CD pipeline guide

Quick start

Action inputs

Action outputs

PR preview workflow

Gate merges with dry-run

Pin the CLI version

Multi-environment deploys

Maintenance windows in CI

Troubleshooting

Next steps