Skip to main content
By the end of this guide, you’ll have a GitHub Actions workflow that validates, plans, and deploys your monitoring config on every push to main, with plan previews on pull requests.
  • A devhelm.yml file in your repository — see Monitoring as Code tutorial
  • A DevHelm API token stored as a GitHub secret (DEVHELM_API_TOKEN)

​
Deploy workflow

Create .github/workflows/devhelm-deploy.yml: 
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
The --yes flag skips interactive confirmation — required for non-interactive CI environments.

​
PR preview workflow

Show what would change before merging. Create .github/workflows/devhelm-plan.yml: 
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 on config validity

Use --dry-run --detailed-exitcode to block PRs that would cause deployment errors: 
      - name: Dry run
        run: devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
Exit codes:
  • 0 — no changes needed
  • 10 — changes pending (valid config, would apply changes)
  • 1 — error (invalid config or API failure)
Use this as a required status check to prevent merging broken configs.

​
Add a maintenance window for deploys

Suppress alerts during the deployment window: 
      - 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

​
Multiple environments

For staging and production environments, see Multi-environment config. Use separate workflow files or environment-specific API tokens: 
jobs:
  deploy-staging:
    environment: staging
    steps:
      - uses: devhelmhq/setup-devhelm@v1
        with:
          api-token: ${{ secrets.DEVHELM_API_TOKEN_STAGING }}
      - 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_PRODUCTION }}
      - run: devhelm deploy -f devhelm.yml --yes

​
Troubleshooting

Another deploy is running. Deploy locks prevent concurrent deploys. Wait for the other deploy to finish, or force unlock if it’s stuck:
devhelm deploy force-unlock --yes
Validation checks syntax offline. The API may reject the config if a referenced secret doesn’t exist or a resource name conflicts. Check the error message for details.
Verify that DEVHELM_API_TOKEN is set as a repository secret (not an environment variable). The action uses it to authenticate all CLI commands.

​
Next steps

Multi-environment config

Manage staging and production separately.

GitHub Actions setup

Full setup-devhelm action reference.

Monitoring as Code tutorial

Complete YAML format and workflow guide.