> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Integration

Set up automated documentation deployments with GitHub Actions, GitLab CI, and other CI/CD platforms.

## Overview

While HolyDocs automatically deploys when you push to your connected Git repository, you may want additional CI/CD integration for validation, conditional deploys, or integration with your existing pipeline.

## GitHub Actions

### Basic Deployment

Create `.github/workflows/docs.yml` in your repository:

```yaml
name: Deploy Documentation
on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'openapi.yaml'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Validate docs
        run: npx @holydocs/cli check --dir ./docs

      - name: Deploy
        run: npx @holydocs/cli deploy --no-watch
        env:
          HOLYDOCS_API_KEY: ${{ secrets.HOLYDOCS_API_KEY }}
          HOLYDOCS_PROJECT: ${{ secrets.HOLYDOCS_PROJECT_ID }}
```

### With Validation on PRs and Deploy on Main

```yaml
name: Docs CI/CD
on:
  push:
    branches: [main]
    paths: ['docs/**']
  pull_request:
    paths: ['docs/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate
        run: npx @holydocs/cli check --dir ./docs

  deploy:
    needs: validate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Deploy to production
        run: npx @holydocs/cli deploy --no-watch
        env:
          HOLYDOCS_API_KEY: ${{ secrets.HOLYDOCS_API_KEY }}
          HOLYDOCS_PROJECT: ${{ secrets.HOLYDOCS_PROJECT_ID }}
```

HolyDocs preview deployments are created by the connected Git provider webhook flow, not by a separate `holydocs deploy --preview` CLI flag.

## GitLab CI

Create `.gitlab-ci.yml` in your repository:

```yaml
stages:
  - validate
  - deploy

validate-docs:
  stage: validate
  image: node:20-alpine
  script:
    - npx @holydocs/cli check --dir ./docs
  rules:
    - changes:
        - docs/**

deploy-docs:
  stage: deploy
  image: node:20-alpine
  script:
    - npx @holydocs/cli deploy --no-watch
  variables:
    HOLYDOCS_API_KEY: $HOLYDOCS_API_KEY
    HOLYDOCS_PROJECT: $HOLYDOCS_PROJECT_ID
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - docs/**
```

## Generic CI (Any Platform)

For any CI platform that supports Node.js, use `npx`:

```bash
# Set environment variables
export HOLYDOCS_API_KEY=hd_a1b2c3d4e5f67890a1b2c3d4e5f67890
export HOLYDOCS_PROJECT=proj_abc123

# Validate first
npx @holydocs/cli check

# Deploy
npx @holydocs/cli deploy --no-watch
```

**CircleCI**

```yaml
    version: 2.1
    jobs:
      deploy-docs:
        docker:
          - image: cimg/node:20.0
        steps:
          - checkout
          - run:
              name: Deploy docs
              command: npx @holydocs/cli deploy --no-watch
    workflows:
      docs:
        jobs:
          - deploy-docs:
              filters:
                branches:
                  only: main
    ```
  **Jenkins**

```groovy
    pipeline {
      agent { docker { image 'node:20-alpine' } }
      stages {
        stage('Deploy Docs') {
          when {
            branch 'main'
            changeset 'docs/**'
          }
          steps {
            withCredentials([string(credentialsId: 'holydocs-api-key', variable: 'HOLYDOCS_API_KEY')]) {
              sh 'npx @holydocs/cli deploy --no-watch'
            }
          }
        }
      }
    }
    ```
  **Bitbucket Pipelines**

```yaml
    pipelines:
      branches:
        main:
          - step:
              name: Deploy Documentation
              image: node:20-alpine
              script:
                - npx @holydocs/cli deploy --no-watch
              condition:
                changesets:
                  includePaths:
                    - "docs/**"
    ```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `HOLYDOCS_API_KEY` | Yes | API key from **Settings > API Keys** |
| `HOLYDOCS_PROJECT` | Usually | Project ID to deploy when you do not have a saved local default |
| `HOLYDOCS_API_URL` | No | Override API base URL (default: `https://api.holydocs.com`) |
| `CI` | Optional | Prevents `holydocs login` from trying to auto-open a browser |

Never commit API keys to your repository. Always use CI secrets or environment variables.

## Monorepo Path Filtering

For monorepos, configure your CI to only trigger on docs changes:

- **GitHub Actions:** Use `paths: ['docs/**']` in the `on.push` trigger
- **GitLab CI:** Use `changes: [docs/**]` in `rules`
- **HolyDocs webhook:** Already filters by `repoPath` — only changes in your docs directory trigger builds

## Best Practices

**Validate Before Deploying**

Always run `holydocs check --dir ./docs` before `holydocs deploy`. Catch config issues in CI before they reach production.
  **Use npx in CI**

Use `npx @holydocs/cli` instead of global install to avoid version caching issues between pipeline runs.
  **Use --no-watch for Speed**

In CI pipelines where you do not need to block on the build result, use `--no-watch` to queue the deployment and exit immediately.
  **Path Filtering**

Only trigger doc deployments when docs files change. This avoids unnecessary builds when only application code changes.

## Notifications on Failure

Set up outbound webhooks to get notified when deployments fail:

```json
{
  "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "events": ["deployment.failed"]
}
```

See [Webhooks](/webhooks) for setup instructions.