CI/CD Integration Guide

Automate documentation in your pipeline

Integrate CodeContext into your CI/CD pipeline to ensure documentation stays perfectly synchronized with your code. This guide covers all major platforms and best practices for automated documentation workflows.

Why Automate Documentation?

Always Current

Docs update with every commit

Quality Gates

Enforce documentation standards

Zero Effort

Set up once, runs forever

GitHub Actions

Basic Documentation Workflow

Create .github/workflows/docs.yml:

docs.yml
name: Update Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  update-docs:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for changelog
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install CodeContext
        run: npm install -g codecontext
      
      - name: Update Documentation
        run: codecontext update
        env:
          CODECONTEXT_API_KEY: ${{ secrets.CODECONTEXT_API_KEY }}
      
      - name: Commit Changes
        if: github.event_name == 'push'
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git diff --quiet && git diff --staged --quiet || git commit -m "docs: auto-update documentation [skip ci]"
          git push

Advanced Workflow with PR Comments

Add documentation preview comments to pull requests:

name: Documentation Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview-docs:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate Docs Preview
        run: |
          npm install -g codecontext
          codecontext update --preview > docs-preview.md
        env:
          CODECONTEXT_API_KEY: ${{ secrets.CODECONTEXT_API_KEY }}
      
      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const preview = fs.readFileSync('docs-preview.md', 'utf8');
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## 📚 Documentation Preview\n\n' + preview
            });

GitLab CI/CD

Add to your .gitlab-ci.yml:

.gitlab-ci.yml
stages:
  - test
  - documentation
  - deploy

update-docs:
  stage: documentation
  image: node:18
  script:
    - npm install -g codecontext
    - codecontext update
    - |
      if [[ -n $(git status -s) ]]; then
        git config user.email "gitlab@example.com"
        git config user.name "GitLab CI"
        git add .
        git commit -m "docs: auto-update documentation [skip ci]"
        git push https://oauth2:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git HEAD:${CI_COMMIT_REF_NAME}
      fi
  only:
    - main
    - develop
  variables:
    CODECONTEXT_API_KEY: ${CODECONTEXT_API_KEY}

# Documentation validation on merge requests
validate-docs:
  stage: test
  image: node:18
  script:
    - npm install -g codecontext
    - codecontext validate
  only:
    - merge_requests

Jenkins Pipeline

Add to your Jenkinsfile:

pipeline {
    agent any
    
    environment {
        CODECONTEXT_API_KEY = credentials('codecontext-api-key')
    }
    
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        
        stage('Update Documentation') {
            when {
                branch 'main'
            }
            steps {
                sh 'npm install -g codecontext'
                sh 'codecontext update'
            }
        }
        
        stage('Commit Documentation') {
            when {
                branch 'main'
                expression { sh(returnStatus: true, script: 'git diff --quiet') != 0 }
            }
            steps {
                sh '''
                    git config user.email "jenkins@example.com"
                    git config user.name "Jenkins"
                    git add .
                    git commit -m "docs: auto-update documentation [skip ci]"
                    git push origin main
                '''
            }
        }
    }
    
    post {
        success {
            echo 'Documentation updated successfully!'
        }
    }
}

CircleCI

Add to your .circleci/config.yml:

version: 2.1

jobs:
  update-docs:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run:
          name: Install CodeContext
          command: npm install -g codecontext
      - run:
          name: Update Documentation
          command: codecontext update
          environment:
            CODECONTEXT_API_KEY: << pipeline.parameters.codecontext_api_key >>
      - run:
          name: Commit Changes
          command: |
            git config user.email "circleci@example.com"
            git config user.name "CircleCI"
            git add .
            git diff --quiet && git diff --staged --quiet || git commit -m "docs: auto-update documentation [skip ci]"
            git push origin $CIRCLE_BRANCH

workflows:
  documentation:
    jobs:
      - update-docs:
          filters:
            branches:
              only:
                - main
                - develop

CI/CD Best Practices

Configuration Tips

  • Use secrets: Store API keys securely in CI/CD secrets
  • Skip CI loops: Add [skip ci] to commit messages
  • Branch filtering: Only update docs on main/production branches
  • Conditional commits: Only commit if files actually changed

Security Considerations

  • Minimal permissions: Use deployment keys with write access only
  • Protected branches: Require PR reviews for doc changes
  • Audit logs: Track all automated documentation updates
  • Rate limiting: Implement throttling for API calls

Advanced CI/CD Patterns

Multi-Stage Documentation Pipeline

Build comprehensive documentation workflows:

  1. 1
    Validate: Check documentation completenesscodecontext validate --strict
  2. 2
    Generate: Create/update documentationcodecontext update --all
  3. 3
    Test: Verify examples and linkscodecontext test
  4. 4
    Deploy: Publish to documentation sitecodecontext deploy

Monorepo Documentation

Handle multiple packages in a monorepo:

# Update all packages
for package in packages/*; do
  if [ -d "$package" ]; then
    echo "Updating docs for $package"
    cd "$package"
    codecontext update
    cd ../..
  fi
done

# Or use workspaces
codecontext update --workspaces

Common CI/CD Issues

Permission Denied

Git push fails with permission error

Solution:

Use deployment tokens with write access or configure SSH keys

Infinite Loop

CI triggers itself repeatedly

Solution:

Add [skip ci] to commit messages

API Rate Limits

Too many requests error

Solution:

Implement caching or upgrade to Pro for higher limits

Quick Reference

Essential CI/CD Commands

codecontext updateUpdate all documentation
codecontext validateCheck documentation quality
codecontext update --previewPreview changes without saving
codecontext statusCheck API usage and limits

Related Topics

Auto-Updates

Automated documentation updates

Team Workflows

Documentation for teams

Update Command

Command line reference

);