Skip to main content
Version: 1.1.0
Last Updated: 2026-04-28
Purpose: Document the optimized CI tiers and the exact command parity for local debugging.

​
Workflow Files

​
Tiered CI Structure

​
Tier 1: Fast PR checks (pull_request)

pr-guardrails.yml runs first, then build.yml runs in parallel:
  1. guardrails
    • PR size limits (changed files and line churn)
    • Commit count limit
    • Generic commit title limit (Changes, Update, WIP, etc.)
    • Override labels for controlled exceptions
build.yml then runs these jobs in parallel:
  1. governance
    • npm run validate:governance
  2. quality
    • npm run format:check -- --tolerate
    • npx turbo run typecheck
    • npm run check-architecture:ci
    • npx turbo run lint:ci
    • npm run docs:comments:baseline (non-blocking)
    • npm run docs:comments:audit:changed
    • npm run audit:settings-consistency
    • hardcoded color audit gate
  3. tests
    • npm run test:coverage (SKIP_SUPABASE_TESTS=true)
    • npx tsx scripts/check-rls-coverage.ts --min-coverage 100
  4. build-and-smoke
    • npx turbo run build
    • npm run perf:build-metrics
    • npm run perf:budgets:check (VITE_BUDGETS_WARN_ONLY=1)
    • npx playwright install --with-deps chromium
    • npm run test:baseline:smoke
  5. non-blocking-analysis
    • npm run check:slop:ci (non-blocking)
    • Dead-code analysis runs in its own deadcode.yml workflow via npm run deadcode:ci (the orchestrator). The legacy raw-fallow check:dead-code* scripts and the check:deps (e18e) advisory step were removed.

​
Tier 2: Main branch validation (push to main)

Uses the same build.yml jobs as Tier 1, plus:
  • Sentry release tagging/deploy metadata in build-and-smoke (push-only step)

​
Tier 3: Deploy workflows

  • supabase-deploy-dev.yml (push to dev with path filters)
  • supabase-deploy-prod.yml (push to production with path filters)
  • supabase-bootstrap-prod.yml (manual break-glass/bootstrap)

​
Tier 4: Scheduled checks

  • governance-weekly.yml (weekly governance + weekly npm audit --audit-level=high)
  • e2e-full.yml (nightly full Playwright suite)
  • migration-lane-audit.yml (weekly informational DB lane audit)
  • db-advisor-quarterly.yml (quarterly issue reminder)

​
CI Minute Controls

  • Concurrency cancellation: enabled on high-churn workflows so superseded runs stop quickly.
  • Path skip filters: docs/spec/config-only changes skip build.yml entirely.
  • Push trigger reduction: full build.yml push checks run on main only (PRs remain the merge gate for dev).
  • Timeouts: explicit timeout-minutes on previously unbounded jobs.
  • Non-blocking analysis isolation: slop/dead-code/dependency health checks moved out of critical path.

​
What To Run Locally Before Push

Primary parity command:
Recommended pre-merge confidence:
For DB-related changes:

​
Manual/GitHub Configuration Follow-ups

  • Configure branch protection required checks for dev, main, and production.
  • Add PR Guardrails / guardrails to required checks on development and production.
  • Enable GitHub secret scanning and push protection in repository settings.
  • Add a CODEOWNERS file for critical CI/deploy paths (.github/workflows/**, supabase/**, src/platform/**).
  • Keep Supabase migration history aligned (supabase migration repair / supabase db pull) when drift is detected.
  • Configure ENCORE_LOVABLE_MIRROR_PAT secret for one-way development mirror workflow.

​
CI pipeline overview (GitHub Actions)

Version: 1.0.0
Last updated: 2026-04-01
Purpose: Map the primary PR/push workflow to local commands so failures are faster to debug.

​
Workflow file

​
Job sequence (high level)

The build job runs in order:
  1. Dependencies: npm ci --legacy-peer-deps
  2. npm audit: npm audit --audit-level=high (fails on high/critical)
  3. Governance: npm run validate:governance
  4. Format: npm run format:check
  5. Types: npm run typecheck
  6. Lint: npm run lint:ci (warning budget enforced in CI)
  7. TSDoc/JSDoc: baseline report (non-blocking) then npm run docs:comments:audit:changed against base/head SHAs
  8. Quality gates (non-blocking unless tuned): check:slop:ci (dead-code analysis runs separately in deadcode.yml via deadcode:ci)
  9. Hardcoded colors: scripts/utils/audit-hardcoded-colors.sh (fails on violations in src)
  10. Settings consistency: npm run audit:settings-consistency (route guards + settings page naming)
  11. Tests: npm run test:coverage with SKIP_SUPABASE_TESTS=true
  12. RLS coverage: npx tsx scripts/check-rls-coverage.ts --min-coverage 100
  13. Production build: npm run build
  14. Sentry: release tagging / deploy metadata (requires SENTRY_AUTH_TOKEN in CI)
  15. Playwright: npx playwright install --with-deps chromium
  16. Smoke gate: npm run test:baseline:smoke with strict env limits (RLS + E2E smoke + audit completeness)
  17. Artifacts: uploads test completeness and doc-comment coverage reports from reports/audits/

​
What to run locally before pushing

For parity with the main gate, prefer:
Or the same steps individually: npm run format:check, npm run typecheck, npm run lint:ci, npm run build, npm run test, npm run test:rls:smoke (or full RLS via npm run test:rls as needed). For a stronger local gate before commit: npm run validate:full (runs validate via Turborepo, then test:unit). See TESTING_SETUP_AND_RUN.md for E2E and env requirements.

​
Non-Blocking Gate Tightening Plan

Step 8 above (check:slop:ci) currently runs with || true to avoid blocking CI while baselines are established. It should be converted to a blocking gate progressively: Process to tighten a gate:
  1. Run the check locally and document current count in a GitHub issue
  2. Create a remediation PR to reduce violations to threshold
  3. Remove || true from the build.yml step
  4. Update this table