stack/packages/mosaic/framework/tools/quality/docs/CI-SETUP.md

CI/CD Configuration Guide

Configure Woodpecker CI, GitHub Actions, or GitLab CI for quality enforcement.

Woodpecker CI

Quality Rails includes .woodpecker.yml template.

Pipeline Stages

1. Secret Scan - gitleaks scans latest commit for hardcoded secrets (runs in parallel, no deps)
2. Install - Dependencies
3. Security Audit - npm audit for CVEs
4. Lint - ESLint checks
5. Type Check - TypeScript compilation
6. Test - Jest with coverage thresholds
7. Build - Production build (gates on all above)

Configuration

No additional configuration needed. Push to repository and Woodpecker runs automatically.

Blocking Merges

Configure Woodpecker to block merges on pipeline failure:

1. Repository Settings → Protected Branches
2. Require Woodpecker pipeline to pass

GitHub Actions

Copy from templates/typescript-node/.github/workflows/quality.yml:

name: Quality Enforcement

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm audit --audit-level=high
      - run: npm run lint
      - run: npm run type-check
      - run: npm run test -- --coverage
      - run: npm run build

Blocking Merges

1. Repository Settings → Branches → Branch protection rules
2. Require status checks to pass: quality

GitLab CI

Copy from templates/typescript-node/.gitlab-ci.yml:

stages:
  - install
  - audit
  - quality
  - build

install:
  stage: install
  script:
    - npm ci

audit:
  stage: audit
  script:
    - npm audit --audit-level=high

lint:
  stage: quality
  script:
    - npm run lint

typecheck:
  stage: quality
  script:
    - npm run type-check

test:
  stage: quality
  script:
    - npm run test -- --coverage

build:
  stage: build
  script:
    - npm run build

Coverage Enforcement

Configure Jest coverage thresholds in package.json:

{
  "jest": {
    "coverageThreshold": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

CI will fail if coverage drops below threshold.

Security Scanning

npm audit

Runs automatically in CI. Adjust sensitivity:

npm audit --audit-level=moderate  # Block moderate+
npm audit --audit-level=high      # Block high+critical only
npm audit --audit-level=critical  # Block critical only

Snyk Integration

Add to CI for additional security:

- run: npx snyk test

Requires SNYK_TOKEN environment variable.

Notification Setup

Woodpecker

Configure in Woodpecker UI:

• Slack/Discord webhooks
• Email notifications
• Status badges

GitHub Actions

Add notification step:

- name: Notify on failure
  if: failure()
  run: |
    curl -X POST $WEBHOOK_URL -d "Build failed"

Troubleshooting

Pipeline fails but pre-commit passed:

• CI runs all packages, pre-commit only checks changed files
• Fix issues in all packages, not just changed files

npm audit blocks on low-severity:

• Adjust --audit-level to moderate or high

Coverage threshold too strict:

• Lower thresholds in package.json
• Add coverage exceptions for specific files