Skip to content

CI_GUIDE.md

Latest commit

 

History

History
214 lines (158 loc) · 5.49 KB

CI_GUIDE.md

File metadata and controls

214 lines (158 loc) · 5.49 KB
Raw

CI Integration Guide & Monorepo Setup

Overview

SigMap integrates into CI to keep your AI context fresh automatically. Run both tools on every push so Copilot and Claude always have an up-to-date understanding of your codebase.

"SigMap for daily always-on context; Repomix for deep one-off sessions — use both."

Quick start — single repo

Copy examples/github-action.yml into .github/workflows/sigmap.yml:

mkdir -p .github/workflows
cp examples/github-action.yml .github/workflows/sigmap.yml
git add .github/workflows/sigmap.yml
git commit -m "ci: add SigMap auto-update workflow"

The workflow runs on every push to main/master and nightly at 02:00 UTC. It commits updated context files back to the branch with [skip ci] to avoid infinite loops.

What the CI workflow does

Job Tool Output When
sigmap gen-context.js .github/copilot-instructions.md every push + nightly
project-map gen-project-map.js PROJECT_MAP.md every push + nightly
repomix repomix --compress .context/repomix-compressed.md every push + nightly
test node test/run.js pass/fail on Node 18/20/22 every push + PR

Monorepo setup

Auto-detection

SigMap v0.5+ automatically detects packages in standard monorepo layouts:

packages/*/package.json    ← npm/yarn/pnpm workspaces
apps/*/package.json        ← Next.js / Turborepo style
services/*/package.json    ← microservices layout
libs/*/package.json
packages/*/Cargo.toml      ← Rust workspaces
packages/*/go.mod          ← Go modules
packages/*/pyproject.toml  ← Python
packages/*/pom.xml         ← Maven / Java
packages/*/build.gradle    ← Gradle / Android

Running monorepo mode

# CLI flag
node gen-context.js --monorepo

# Or set in config
echo '{"monorepo": true}' > gen-context.config.json
node gen-context.js

Output: one CLAUDE.md per detected package:

packages/auth/CLAUDE.md
packages/core/CLAUDE.md
packages/ui/CLAUDE.md
apps/web/CLAUDE.md
...

Monorepo CI workflow

Add a --monorepo step to your workflow:

- name: Generate per-package context
  run: node gen-context.js --monorepo

- name: Commit updated package context files
  uses: stefanzweifel/git-auto-commit-action@v5
  with:
    commit_message: "chore(context): auto-update per-package AI context [skip ci]"
    file_pattern: "packages/**/CLAUDE.md apps/**/CLAUDE.md services/**/CLAUDE.md"

Excluding files from context

.contextignore (SigMap-specific)

# Exclude legacy and generated code
src/legacy/**
src/generated/**
**/*.pb.ts
**/*.generated.ts

# Exclude large test fixtures
test/fixtures/large-*

.repomixignore (shared with Repomix)

# Works for both SigMap and Repomix
node_modules/
dist/
build/
*.min.js

Both files are merged automatically — no separate configuration needed.

Tip: Symlink one to the other so you maintain a single exclusion file:

ln -s .contextignore .repomixignore

Git-diff priority

When diffPriority: true (the default), recently git-committed files appear first in the generated output and are protected from token-budget drops.

{
  "diffPriority": true
}

This means fresh changes are always reflected prominently in AI context — an agent opening the project after your latest commit will immediately see what changed.

Token report in CI

Use --report --json to capture token metrics as structured output:

- name: Token report
  run: |
    node gen-context.js --report --json | tee /tmp/cf-report.json
    echo "Final tokens: $(cat /tmp/cf-report.json | node -e 'process.stdin.resume();let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>console.log(JSON.parse(d).finalTokens))')"

JSON schema:

{
  "version": "6.5.0",
  "timestamp": "2026-04-01T09:00:00.000Z",
  "rawTokens": 42000,
  "finalTokens": 2800,
  "fileCount": 120,
  "droppedCount": 8,
  "reductionPct": 93.3,
  "overBudget": false,
  "budgetLimit": 6000
}

CI helper script (v1.0)

scripts/ci-update.sh wraps the common CI pattern:

# Regenerate, track, and fail the build if over budget
bash scripts/ci-update.sh --fail-over-budget --track

# Regenerate + cache sidecar + JSON report (no fail)
bash scripts/ci-update.sh --format cache --json

Health gate (v1.0)

Add a health check step to catch degradation before it affects acceptance rate:

- name: SigMap health check
  run: node gen-context.js --health --json
  # Prints score/grade/staleness; use --json to capture for dashboards

Troubleshooting

Symptom Fix
Context file is stale Re-run node gen-context.js or check the nightly schedule
Too many tokens (> 6K) Lower maxTokens or add patterns to .contextignore
Package not detected in monorepo Ensure directory has a manifest (package.json, Cargo.toml, etc.)
Secret appears in output Add pattern to src/security/patterns.js or use .contextignore for that file
CI write permission denied Add permissions: contents: write to the workflow job

Related docs