> ## 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.

# Generic CI/CD

> Deploy DevHelm monitoring config from any CI/CD system — GitLab, Jenkins, CircleCI, and more

Use the DevHelm CLI in any CI system that can install npm packages. This page shows patterns for common CI providers.

## Requirements

* **Node.js 18+** on the CI runner
* **`DEVHELM_API_TOKEN`** set as a CI secret
* A `devhelm.yml` config file in your repository

## Standard workflow

```bash theme={null}
npm install -g devhelm
devhelm validate devhelm.yml
devhelm deploy -f devhelm.yml --yes
```

## GitLab CI

```yaml theme={null}
deploy-monitoring:
  image: node:20
  stage: deploy
  only:
    changes: [devhelm.yml]
  script:
    - npm install -g devhelm
    - devhelm validate devhelm.yml
    - devhelm deploy -f devhelm.yml --yes
  variables:
    DEVHELM_API_TOKEN: $DEVHELM_API_TOKEN

plan-monitoring:
  image: node:20
  stage: test
  only:
    refs: [merge_requests]
    changes: [devhelm.yml]
  script:
    - npm install -g devhelm
    - devhelm validate devhelm.yml
    - devhelm plan -f devhelm.yml
  variables:
    DEVHELM_API_TOKEN: $DEVHELM_API_TOKEN
```

## Jenkins

```groovy theme={null}
pipeline {
    agent { docker { image 'node:20' } }
    environment {
        DEVHELM_API_TOKEN = credentials('devhelm-api-token')
    }
    stages {
        stage('Validate') {
            when { changeset 'devhelm.yml' }
            steps {
                sh 'npm install -g devhelm'
                sh 'devhelm validate devhelm.yml'
            }
        }
        stage('Deploy') {
            when {
                allOf {
                    changeset 'devhelm.yml'
                    branch 'main'
                }
            }
            steps {
                sh 'devhelm deploy -f devhelm.yml --yes'
            }
        }
    }
}
```

## CircleCI

```yaml theme={null}
version: 2.1
jobs:
  plan:
    docker: [{ image: cimg/node:20.0 }]
    steps:
      - checkout
      - run: npm install -g devhelm
      - run: devhelm validate devhelm.yml
      - run: devhelm plan -f devhelm.yml

  deploy:
    docker: [{ image: cimg/node:20.0 }]
    steps:
      - checkout
      - run: npm install -g devhelm
      - run: devhelm deploy -f devhelm.yml --yes

workflows:
  monitoring:
    jobs:
      - plan:
          filters:
            branches:
              ignore: main
      - deploy:
          filters:
            branches:
              only: main
```

## Bitbucket Pipelines

```yaml theme={null}
pipelines:
  pull-requests:
    '**':
      - step:
          name: Plan monitoring config
          image: node:20
          script:
            - npm install -g devhelm
            - devhelm validate devhelm.yml
            - devhelm plan -f devhelm.yml
  branches:
    main:
      - step:
          name: Deploy monitoring config
          image: node:20
          script:
            - npm install -g devhelm
            - devhelm deploy -f devhelm.yml --yes
```

## Version pinning

For reproducible builds, pin the CLI version:

```bash theme={null}
npm install -g devhelm@1.3.0
```

## Gating merges

Use `--dry-run --detailed-exitcode` as a required status check:

```bash theme={null}
devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
```

Exit `10` means changes are pending — use this to require review before merging config changes. Exit `0` means no changes; validation failures exit `4` and API errors exit `11`.

## Next steps

<CardGroup cols={2}>
  <Card title="GitHub Actions" icon="github" href="/mac/ci-cd/github-actions">
    Official setup-devhelm action with caching.
  </Card>

  <Card title="Multi-environment" icon="layer-group" href="/mac/ci-cd/multi-environment">
    Deploy staging and production separately.
  </Card>
</CardGroup>