CI/CD Integration

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 Documentationon:  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/CDon:  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  - deployvalidate-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 variablesexport HOLYDOCS_API_KEY=hd_a1b2c3d4e5f67890a1b2c3d4e5f67890export HOLYDOCS_PROJECT=proj_abc123# Validate firstnpx @holydocs/cli check# Deploynpx @holydocs/cli deploy --no-watch

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

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'        }      }    }  }}

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

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

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 for setup instructions.