Skip to content

CI/CD Integration

CKB becomes your single source of truth for change risk in CI/CD pipelines. Instead of treating code review as a human-only process, CKB provides precomputed analysis that travels with every PR.

Looking for ready-to-use workflows? See Workflow Examples for production-ready templates for GitHub Actions, GitLab CI, and local git hooks—with example PR comment outputs.

Want to enforce code standards? See Quality Gates for configuring complexity, risk, coupling, and coverage gates.

All workflow files are in the examples/ directory.

Getting Started

Choose a workflow based on your needs:

I want to... Platform Workflow
Get started quickly GitHub pr-analysis.yml
Customize with optional features GitHub starter-template.yml
See all CKB capabilities GitHub full-showcase.yml
Use GitLab CI GitLab ckb.yml

Copy the workflow to your .github/workflows/ (or .gitlab-ci.yml) and customize as needed.

Quick install (works in any CI):

npm install -g @tastehub/ckb
ckb init
ckb index
ckb serve --port 8080 &

Then call the API (see workflows for full examples):

curl -X POST http://localhost:8080/pr/summary \
  -H "Content-Type: application/json" \
  -d '{"baseBranch": "main", "headBranch": "HEAD"}'

What CKB Provides in CI

  • Blast radius — Know exactly what breaks before merging
  • Suggested reviewers — Based on actual code ownership, not guesswork
  • Boundary detection — Flag when "local" changes cross API contracts
  • Risk scoring — Quantified risk based on hotspots, module spread, and history
  • Complexity gates — Block merges that exceed complexity thresholds
  • Coupling analysis — Warn when tightly-coupled files change independently
  • Dead code detection — Identify unused code from static analysis
  • Affected tests — Run only tests affected by changes
  • Documentation coverage — Enforce doc coverage and detect stale references

The pattern: start the server (ckb serve) and call the HTTP API. CLI commands are also available for local use and scripting.

How It Works

When you call ckb pr-summary, CKB:

  1. Diffs the branches using git (base vs head)
  2. Maps files to modules based on path structure
  3. Checks each file against hotspot data — flags files with score > 0.5
  4. Queries ownership for each changed file (CODEOWNERS + git-blame)
  5. Calculates risk based on: file count, lines changed, hotspots touched, module spread
  6. Returns structured JSON with everything a PR comment needs

Example response:

{
  "summary": {
    "totalFiles": 12,
    "totalAdditions": 450,
    "totalDeletions": 120,
    "totalModules": 3,
    "hotspotsTouched": 2
  },
  "riskAssessment": {
    "level": "medium",
    "score": 0.45,
    "factors": ["Touches 2 hotspot(s)", "Spans 3 modules"],
    "suggestions": ["Extra review recommended for hotspot files"]
  },
  "suggestedReviewers": [
    {"owner": "@api-team", "reason": "Owns 8 of 12 changed files", "coverage": 0.67}
  ],
  "modulesAffected": [
    {"moduleId": "internal/api", "filesChanged": 8, "riskLevel": "medium"}
  ]
}

Installation in CI

npm (Recommended):

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

- name: Install CKB
  run: npm install -g @tastehub/ckb

npx (no install):

- name: Run CKB
  run: npx @tastehub/ckb pr-summary --base=main

Pre-built binary:

- run: |
    curl -sSL https://github.com/SimplyLiz/CodeMCP/releases/latest/download/ckb_linux_amd64.tar.gz | tar xz
    sudo mv ckb /usr/local/bin/

Build from source:

- uses: actions/setup-go@v5
  with:
    go-version: '1.22'

- run: |
    git clone https://github.com/SimplyLiz/CodeMCP.git /tmp/codemcp
    cd /tmp/codemcp && go build -o /usr/local/bin/ckb ./cmd/ckb

Critical: Full Git History

CKB needs git history for ownership analysis. Without it, suggested reviewers will be empty.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Required for git-blame analysis

Environment Validation

Before running CKB analysis, validate that your CI environment has the required tooling:

- name: Validate CKB Environment
  run: |
    RESULT=$(ckb doctor --tier=standard --format json)
    MISSING=$(echo "$RESULT" | jq '[.languages[] | select(.status == "missing")] | length')

    if [ "$MISSING" -gt 0 ]; then
      echo "::warning::Missing $MISSING language tools"
      ckb doctor --tier=standard
    fi

Tier Requirements

Tier Tools Required Use Case
fast None (tree-sitter built-in) Quick PR checks
standard SCIP indexers (scip-go, scip-typescript, etc.) Full code intelligence
full Standard + LSP servers Maximum accuracy

CLI Commands for CI

These commands work directly without starting a server:

# PR analysis
ckb pr-summary --base=main --head=HEAD

# Impact analysis
ckb impact diff --base=main --format=json
ckb impact --range=main..HEAD --format=markdown

# Affected tests
ckb affected-tests --range=main..HEAD --output=command

# Suggested reviewers
ckb reviewers --range=main..HEAD --format=gh

# Complexity analysis
ckb complexity internal/query/engine.go --format=json

# Coupling analysis
ckb coupling --files=file1.go,file2.go --min-correlation=0.7

# Risk audit
ckb audit --min-score=60 --limit=20

# Dead code detection
ckb dead-code --threshold=0.9 --limit=20

# Hotspots
ckb hotspots --limit=20

# Ownership drift
ckb ownership --drift --threshold=0.3

HTTP API Endpoints

Start the server first: ckb serve --port 8080 &

Endpoint Method Description
/pr/summary POST PR analysis with ownership
/ownership/drift GET CODEOWNERS accuracy check
/hotspots GET High-churn files
/architecture/refresh POST Rebuild cached analysis
/jobs/:id GET Check async job status
/health GET Liveness probe
/ready GET Readiness probe
/metrics GET Prometheus metrics
/telemetry/dead-code GET Dead code candidates
/meta/languages GET Language quality dashboard
/cache/warm POST Pre-warm cache
/cache/clear POST Clear cache
/complexity GET File complexity analysis
/contracts/impact GET Contract change impact

Example:

curl -s -X POST http://localhost:8080/pr/summary \
  -H "Content-Type: application/json" \
  -d '{"baseBranch": "main"}'

Incremental Indexing

For Go projects, CKB supports incremental indexing that only processes changed files. This dramatically speeds up CI pipelines.

Scenario Full Index Incremental
Large Go project (10k files) ~60s ~2-5s
Typical PR (5-10 files) ~60s ~1-2s
Single file hotfix ~60s <1s

Key insight: PR pipelines typically change a small fraction of files. Incremental indexing is O(changed files), not O(total files).

Caching Strategy

- name: Restore Cache
  uses: actions/cache@v4
  with:
    path: .ckb/
    key: ckb-${{ runner.os }}-${{ github.ref }}-${{ github.sha }}
    restore-keys: |
      ckb-${{ runner.os }}-${{ github.ref }}-
      ckb-${{ runner.os }}-

- name: Index
  run: |
    ckb init
    ckb index  # Incremental by default

- name: Save Cache
  uses: actions/cache/save@v4
  if: always()
  with:
    path: .ckb/
    key: ckb-${{ runner.os }}-${{ github.ref }}-${{ github.sha }}

Use ckb index --force for nightly builds when accuracy matters. Use incremental for PRs when speed matters.

See Incremental Indexing for accuracy guarantees and troubleshooting.

Trigger Refresh via API (v7.5)

If running the CKB daemon, trigger index refresh via HTTP:

# Incremental refresh (fastest)
curl -X POST http://localhost:9120/api/v1/refresh

# Full reindex (when accuracy is critical)
curl -X POST http://localhost:9120/api/v1/refresh -d '{"full": true}'

# Specify repository path
curl -X POST http://localhost:9120/api/v1/refresh -d '{"repo": "/path/to/repo"}'

This is useful for:

  • Post-deploy hooks that need fresh indexes
  • Scheduled jobs that maintain index freshness
  • Integration with external build systems

See Daemon-Mode#index-refresh-api-v75 for full documentation.

Change Impact Analysis

CKB's Change Impact Analysis maps git diffs to SCIP symbols, then uses the call graph to identify what downstream code might break.

Output Formats

Format Use Case
--format=json Machine-readable for scripting
--format=markdown PR comments, GitHub/GitLab integration
--format=text Human-readable terminal output (default)

ROI: Real CI Savings

Scenario Full Suite With Affected Tests Savings
10,000 tests, 45 min 45 min ~5 min (typical PR) 89%
50 CI runs/day 37.5 hours ~4 hours $500+/day*

*Assuming $0.008/min for CI compute

See Impact-Analysis for full documentation including risk scoring and confidence levels.

Complexity Gates

Fail CI when code complexity exceeds thresholds. High cyclomatic complexity correlates with bugs and maintenance burden.

# Check a single file
ckb complexity internal/query/engine.go --format=json

# Response includes:
{
  "summary": {
    "maxCyclomatic": 12,
    "maxCognitive": 18,
    "averageCyclomatic": 2.71
  },
  "functions": [
    {"name": "Execute", "cyclomatic": 8, "cognitive": 12, "risk": "medium"}
  ]
}

See Workflow Examples#complexity-gate for a complete workflow.

Dead Code Detection

Identify unused code using static analysis:

ckb dead-code --threshold=0.9 --limit=20 --format=json

Response includes confidence scores and reasons:

{
  "candidates": [
    {
      "symbol": "legacyHandler",
      "path": "internal/api/legacy.go:45",
      "reason": "No references found in codebase",
      "confidence": 0.95
    }
  ]
}

See Workflow Examples#dead-code-detection for automated weekly scans.

Coupling Analysis

Detect tightly coupled files that change together. Warns when coupled files change independently:

ckb coupling --files=handler.go,service.go --min-correlation=0.7

Response:

{
  "changedFiles": ["internal/api/handler.go"],
  "missingCoupled": [
    {
      "file": "internal/api/handler_test.go",
      "coupledTo": "internal/api/handler.go",
      "couplingScore": 0.92,
      "cochangeCount": 45
    }
  ]
}

Risk Audit

Comprehensive 8-factor risk analysis:

Factor Weight Description
complexity 20% Cyclomatic/cognitive complexity
test_coverage 20% Percentage of code covered by tests
bus_factor 15% Number of contributors
security_sensitive 15% Contains auth/crypto/credential code
staleness 10% Time since last modification
error_rate 10% Runtime errors from telemetry
co_change_coupling 5% Tightly coupled files
churn 5% Frequency of changes 
ckb audit --min-score=60 --limit=20 --format=json

See Workflow Examples#risk-audit for weekly risk audits.

Contract-Aware CI

When changes touch API contracts (protobuf, OpenAPI), CKB can detect cross-boundary impact that simple file diffs miss.

curl -s "http://localhost:8080/contracts/impact?path=proto/api/v1/user.proto"

Response:

{
  "contract": "proto/api/v1/user.proto",
  "visibility": "public",
  "consumers": [
    {"repo": "frontend", "confidence": "high"},
    {"repo": "mobile-app", "confidence": "medium"}
  ],
  "riskLevel": "high",
  "riskFactors": ["Public contract with 2 known consumers"]
}

See Workflow Examples#contract-check for contract safety workflows.

Documentation Coverage CI

Enforce documentation coverage and detect stale symbol references:

# Check coverage
ckb docs coverage --fail-under=80

# Find stale references
ckb docs stale --all --format=json

# Check docs for a symbol before renaming
ckb docs symbol "UserService.Authenticate"

See Workflow Examples#doc-quality for documentation quality workflows.

Health and Readiness Checks

For Kubernetes deployments:

Endpoint Purpose Response
GET /health Liveness probe {"status": "ok"}
GET /health/detailed Full component status Status of each subsystem
GET /ready Readiness probe 200 if ready, 503 if not 
# Kubernetes probes
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 5

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 2

Prometheus Metrics

CKB exports metrics in Prometheus format:

Metric Type Description
ckb_requests_total Counter Total API requests
ckb_request_duration_seconds Histogram Request latency
ckb_cache_hits_total Counter Cache hit count
ckb_symbols_indexed Gauge Number of indexed symbols
ckb_index_age_seconds Gauge Time since last index 
curl -s http://localhost:8080/metrics

Cache Management

Pre-warming Cache

curl -X POST "http://localhost:8080/cache/warm" \
  -H "Content-Type: application/json" \
  -d '{"scope": "architecture"}'

Clearing Cache

# Clear all cache
curl -X POST "http://localhost:8080/cache/clear"

# Clear specific tier
curl -X POST "http://localhost:8080/cache/clear" \
  -H "Content-Type: application/json" \
  -d '{"tier": "query"}'

Cache Tiers

Tier Contents TTL
query Symbol lookups, references 5 min
view Architecture, hotspots 1 hour
negative "Not found" results 10 min

Upload to Central Index Server

For organizations using a central CKB index server:

- name: Upload Index
  env:
    CKB_TOKEN: ${{ secrets.CKB_TOKEN }}
  run: |
    curl -X POST "${{ vars.CKB_SERVER_URL }}/index/repos/${{ github.repository }}/upload" \
      -H "Authorization: Bearer $CKB_TOKEN" \
      -H "Content-Type: application/octet-stream" \
      -H "Content-Encoding: gzip" \
      -H "X-CKB-Commit: ${{ github.sha }}" \
      --data-binary @<(gzip -c index.scip)

See Authentication for token configuration.

Environment Variables

Variable Description Default
CKB_REPO_ROOT Repository root path Current directory
CKB_LOG_LEVEL Log verbosity (debug/info/warn/error) info
CKB_CONFIG_PATH Config file location .ckb/config.json
CKB_TIER Analysis tier: fast, standard, or full Auto-detected

Tips

  1. Cache the .ckb/ directory — Enables incremental indexing across runs
  2. Use fetch-depth: 0 — Required for git-blame analysis
  3. Run refresh on schedule — Keep data fresh without blocking PRs
  4. Use async for big repos — Avoid CI timeout issues with /architecture/refresh?async=true
  5. Use incremental indexing for PRs — O(changed files) instead of O(total files)
  6. Use --force for nightly builds — Ensures maximum accuracy
  7. Validate with ckb doctor --tier — Catch missing tools early
  8. Use /ready for health checks — Wait for server before queries
  9. Export /metrics for dashboards — Track CKB performance over time
  1. Start with PR comments (informational only)
  2. Add hotspot warnings after you trust the data
  3. Add contract boundary detection for API changes
  4. Consider ownership drift on a schedule, not every PR
  5. Add enforcement (failing builds) only after the team trusts the signals

Workflow Templates

Ready-to-use workflow files are available in the examples/ directory:

Directory Contents
examples/github-actions/ 13 GitHub Actions workflows
examples/gitlab-ci/ Complete GitLab CI configuration
examples/hooks/ Git hooks, pre-commit framework, Husky

See Workflow Examples for full documentation of each workflow with example outputs.