---
name: kodadocs-docs-ci
description: "Generate CI/CD workflows to auto-regenerate and deploy documentation on push to main, with PR preview deployments."
---

# Docs CI/CD Generator

## Overview

This skill generates continuous integration and deployment workflows that automatically regenerate your KodaDocs documentation site when code is pushed to your main branch. It also configures preview deployments for pull requests so reviewers can see documentation changes before merging.

Use this skill when:
- You want documentation to stay in sync with code changes automatically
- You want PR reviewers to preview documentation changes
- You are setting up a new project and want docs CI from the start
- You need a CI workflow for GitHub Actions or GitLab CI

## Prerequisites

Before running this skill, ensure the following:

1. **KodaDocs installed:** The `kodadocs` package must be available via PyPI.
2. **Existing doc site:** A KodaDocs doc site should have been generated at least once (`.kodadocs/run_manifest.json` exists).
3. **CI platform access:** Write access to `.github/workflows/` (GitHub) or `.gitlab-ci.yml` (GitLab).
4. **Deployment provider credentials:** API tokens for the target deployment platform.

## Workflow

### Step 1: Detect CI Platform and Framework

**CI platform detection:**
- `.github/` directory exists -> GitHub Actions
- `.gitlab-ci.yml` exists -> GitLab CI
- Both exist -> Ask the user which platform to target
- Neither exists -> Ask the user; default to GitHub Actions if remote is github.com

**Framework detection:**
Call `mcp__kodadocs__detect_framework` with the project path. This determines how to start the application in CI, which build commands to run, and what port the dev server uses.

**Deployment platform detection:**
Check the manifest via `mcp__kodadocs__load_manifest` for the `provider` field. Supported providers: `kodadocs`, `cloudflare`, `vercel`, `netlify`, `github-pages`.

### Step 2: Determine Application Startup Commands

Based on the detected framework, set the install command, dev server command, port, and health check.

| Framework | Install | Dev Server | Port | Health Check |
|-----------|---------|-----------|------|-------------|
| Next.js | `npm ci` | `npm run dev` | 3000 | `curl -s http://localhost:3000` |
| Nuxt | `npm ci` | `npm run dev` | 3000 | `curl -s http://localhost:3000` |
| SvelteKit | `npm ci` | `npm run dev` | 5173 | `curl -s http://localhost:5173` |
| React (Vite) | `npm ci` | `npm run dev` | 5173 | `curl -s http://localhost:5173` |
| Django | `pip install -r requirements.txt` | `python manage.py runserver` | 8000 | `curl -s http://localhost:8000` |
| Flask | `pip install -r requirements.txt` | `flask run` | 5000 | `curl -s http://localhost:5000` |
| Rails | `bundle install` | `rails server` | 3000 | `curl -s http://localhost:3000` |

If the framework is not recognized, ask the user for the install command, dev server command, port, and any required environment variables.

**Screenshot-less mode:** If the application cannot be started in CI (requires external services, complex setup), skip screenshot capture and generate text-only documentation. Note this in the workflow comments.

### Step 3: Generate GitHub Actions Workflow

Generate `.github/workflows/docs.yml` with both deploy-on-push and PR preview jobs:

```yaml
name: Generate & Deploy Docs

on:
  push:
    branches: [main]
    paths: ['src/**', 'app/**', 'pages/**', 'components/**', 'lib/**', 'package.json', '.kodadocs/**']
  pull_request:
    paths: ['src/**', 'app/**', 'pages/**', 'components/**', 'lib/**', 'package.json']
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

jobs:
  generate-docs:
    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: pip install kodadocs && playwright install chromium --with-deps
      - run: <INSTALL_COMMAND>
      - name: Start application
        run: |
          <DEV_SERVER_COMMAND> &
          for i in $(seq 1 30); do
            <HEALTH_CHECK> > /dev/null 2>&1 && break || sleep 2
          done
      - name: Generate and deploy documentation
        env:
          KODADOCS_LICENSE_KEY: ${{ secrets.KODADOCS_LICENSE_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --mcp kodadocs \
            "Generate documentation for this project. \
             App URL: http://localhost:<PORT>. Deploy to <PROVIDER>."
      - if: always()
        run: kill $(lsof -t -i:<PORT>) 2>/dev/null || true

  preview-docs:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: pip install kodadocs && playwright install chromium --with-deps
      - run: <INSTALL_COMMAND>
      - name: Start application
        run: |
          <DEV_SERVER_COMMAND> &
          for i in $(seq 1 30); do
            <HEALTH_CHECK> > /dev/null 2>&1 && break || sleep 2
          done
      - name: Generate and deploy preview
        id: preview
        env:
          KODADOCS_LICENSE_KEY: ${{ secrets.KODADOCS_LICENSE_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          SLUG="preview-pr-${{ github.event.pull_request.number }}"
          claude --mcp kodadocs \
            "Generate documentation for this project. \
             App URL: http://localhost:<PORT>. \
             Deploy to kodadocs with slug ${SLUG}."
          echo "url=https://${SLUG}.kodadocs.com" >> $GITHUB_OUTPUT
      - name: Comment preview URL on PR
        uses: actions/github-script@v7
        with:
          script: |
            const url = '${{ steps.preview.outputs.url }}';
            const body = `## Docs Preview\n\n${url}\n\nUpdated on each push.`;
            const comments = await github.rest.issues.listComments({
              owner: context.repo.owner, repo: context.repo.repo,
              issue_number: context.issue.number,
            });
            const existing = comments.data.find(c =>
              c.body.includes('Docs Preview') && c.user.type === 'Bot');
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner, repo: context.repo.repo,
                comment_id: existing.id, body });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner, repo: context.repo.repo,
                issue_number: context.issue.number, body });
            }
      - if: always()
        run: kill $(lsof -t -i:<PORT>) 2>/dev/null || true
```

### Step 4: Generate GitLab CI Configuration (Alternative)

If GitLab CI is the target, generate or append to `.gitlab-ci.yml`:

```yaml
stages:
  - docs

.docs-base:
  image: python:3.11
  before_script:
    - apt-get update && apt-get install -y nodejs npm
    - pip install kodadocs && playwright install chromium --with-deps
    - <INSTALL_COMMAND>

generate-docs:
  extends: .docs-base
  stage: docs
  only:
    refs: [main]
    changes: ['src/**/*', 'app/**/*', 'pages/**/*', 'components/**/*', 'package.json']
  script:
    - <DEV_SERVER_COMMAND> &
    - for i in $(seq 1 30); do <HEALTH_CHECK> > /dev/null 2>&1 && break || sleep 2; done
    - claude --mcp kodadocs "Generate docs. App URL http://localhost:<PORT>. Deploy to <PROVIDER>."
  artifacts: { paths: [.kodadocs/], expire_in: 7 days }

docs-preview:
  extends: .docs-base
  stage: docs
  only: [merge_requests]
  script:
    - <DEV_SERVER_COMMAND> &
    - for i in $(seq 1 30); do <HEALTH_CHECK> > /dev/null 2>&1 && break || sleep 2; done
    - SLUG="preview-mr-${CI_MERGE_REQUEST_IID}"
    - claude --mcp kodadocs "Generate docs. App URL http://localhost:<PORT>. Deploy to kodadocs with slug ${SLUG}."
  environment:
    name: docs-preview/$CI_MERGE_REQUEST_IID
    url: https://preview-mr-${CI_MERGE_REQUEST_IID}.kodadocs.com
```

### Step 5: Configure Secrets

Generate a setup guide for required CI secrets.

**Required secrets (all providers):**

| Secret Name | Description | Source |
|-------------|-------------|--------|
| `KODADOCS_LICENSE_KEY` | KodaDocs Pro license key | app.kodadocs.com dashboard |
| `ANTHROPIC_API_KEY` | Claude API key | console.anthropic.com |

**Provider-specific secrets:**

| Provider | Secret Name | Description |
|----------|-------------|-------------|
| Cloudflare | `CLOUDFLARE_API_TOKEN` | API token with Pages permissions |
| Vercel | `VERCEL_TOKEN` | Personal access token from vercel.com/account/tokens |
| Netlify | `NETLIFY_AUTH_TOKEN` | Token from app.netlify.com/user/applications |
| GitHub Pages | (none) | Uses built-in GITHUB_TOKEN |
| KodaDocs | (none) | Uses KODADOCS_LICENSE_KEY |

**GitHub Actions:** Settings > Secrets and variables > Actions > New repository secret.

**GitLab CI:** Settings > CI/CD > Variables > Add variable (check "Mask variable").

### Step 6: Configure Path Filters

Customize which file changes trigger a docs rebuild.

**Framework-specific path additions:**

| Framework | Additional Paths |
|-----------|-----------------|
| Next.js | `next.config.*`, `middleware.*` |
| Nuxt | `nuxt.config.*`, `server/**` |
| SvelteKit | `svelte.config.*`, `vite.config.*` |
| Django | `**/urls.py`, `**/views.py`, `templates/**` |
| Rails | `config/routes.rb`, `app/views/**` |

**Paths that should never trigger docs rebuild:**
```yaml
paths-ignore: ['*.md', '.github/**', 'tests/**', '.gitignore', 'LICENSE']
```

### Step 7: Save and Validate Workflow Files

**Save locations:**
- GitHub Actions: `.github/workflows/docs.yml`
- GitLab CI: append to `.gitlab-ci.yml` (or create new)

**Replace all placeholders** before saving:
- `<INSTALL_COMMAND>`, `<DEV_SERVER_COMMAND>`, `<HEALTH_CHECK>`, `<PORT>` from Step 2
- `<PROVIDER>`, `<PROVIDER_TOKEN_ENV>`, `<PROVIDER_TOKEN_SECRET>` from Step 1

**Validation checks:**
1. YAML syntax is valid
2. All `<...>` placeholders have been replaced
3. Secret names match between workflow and setup guide
4. Path filters include framework-specific paths
5. Concurrency groups prevent parallel doc builds
6. Timeout is 15 minutes (small projects) or 30 minutes (large projects)

If validation fails, fix the issue and re-save. Do not leave broken workflow files.

## Decision Trees

### CI Platform Selection

```
Does .github/workflows/ exist?
  YES -> GitHub Actions
Does .gitlab-ci.yml exist?
  YES -> GitLab CI
Both exist?
  -> Ask the user which to configure
Neither exists?
  -> Default to GitHub Actions if remote is github.com, otherwise ask
```

### Screenshot Mode

```
Can the application start in CI?
  Check: Does a dev server command exist? Does it need external services?
  YES (standalone app) -> Full pipeline with screenshots
  MAYBE (needs DB/Redis) -> Add Docker services, include screenshots
  NO (too complex) -> Text-only docs, comment explaining why screenshots were skipped
```

### Existing CI Configuration

```
Does a CI workflow file already exist?
  YES -> Does it have a docs job already?
           YES -> Ask: "Replace existing docs job or create a separate file?"
           NO  -> Add docs job alongside existing jobs
  NO  -> Create workflow file from scratch
```

### Provider Authentication

```
kodadocs    -> Only needs KODADOCS_LICENSE_KEY
github-pages -> Only needs GITHUB_TOKEN (built-in)
cloudflare   -> Needs CLOUDFLARE_API_TOKEN + KODADOCS_LICENSE_KEY
vercel       -> Needs VERCEL_TOKEN + KODADOCS_LICENSE_KEY
netlify      -> Needs NETLIFY_AUTH_TOKEN + KODADOCS_LICENSE_KEY
```

## Output Format

The skill produces:

1. **CI workflow file(s)** - GitHub Actions YAML or GitLab CI YAML
2. **Secret setup guide** - Instructions for configuring required secrets
3. **Console summary:**

```
Docs CI/CD configured:
  Platform: GitHub Actions
  Framework: Next.js
  Deploy provider: kodadocs
  Files created:
    - .github/workflows/docs.yml (deploy on push + PR preview)
  Required secrets: KODADOCS_LICENSE_KEY, ANTHROPIC_API_KEY
  Path triggers: src/**, app/**, pages/**, components/**, package.json
  Screenshot capture: enabled (port 3000)
  Next step: Add secrets in GitHub Settings > Secrets and variables > Actions
```

## Error Handling

### No package manager detected
If no `package.json`, `requirements.txt`, or `Gemfile` exists:
- Ask the user to specify the install command manually
- Do not generate a workflow with a missing install step

### Conflicting CI files
If both `.github/workflows/` and `.gitlab-ci.yml` exist:
- Ask the user which platform to target. Generate only one workflow.

### Invalid YAML in existing CI file
If `.gitlab-ci.yml` has syntax errors:
- Warn: "Existing .gitlab-ci.yml has syntax errors. Fix them before adding the docs job."
- Do not append to a broken file

### Missing manifest
If `.kodadocs/run_manifest.json` does not exist:
- Warn: "No previous KodaDocs run detected. CI will run the full pipeline from scratch."
- This is acceptable and not a blocking error

### Application cannot start in CI
If the application requires complex infrastructure:
- Use text-only mode (no screenshots)
- Add a workflow comment explaining why
- Suggest Docker services or docker-compose for full pipeline support

### Rate limits on Claude API
- Concurrency groups prevent parallel runs
- Path filters prevent unnecessary triggers
- If still hitting limits: suggest a schedule trigger instead of push-on-every-commit

## Success Criteria

The run is successful when:
- [ ] CI platform was correctly detected or chosen
- [ ] Framework was detected and startup commands were set
- [ ] Deployment provider was identified from manifest or user input
- [ ] Workflow file was generated with all placeholders replaced
- [ ] YAML syntax is valid
- [ ] Path filters are appropriate for the project
- [ ] Secret setup guide lists all required secrets
- [ ] PR preview deployment is configured
- [ ] Concurrency prevents parallel doc builds
- [ ] Workflow files were saved to the correct locations
- [ ] Console summary was printed with configuration details
