> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CI Pipeline Overview (GitHub Actions)

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

**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

* **Main gate:** [`.github/workflows/build.yml`](../../.github/workflows/build.yml)
* **PR guardrails:** [`.github/workflows/pr-guardrails.yml`](../../.github/workflows/pr-guardrails.yml)
* **DB migration guard:** [`.github/workflows/db-migration-guard.yml`](../../.github/workflows/db-migration-guard.yml)
* **Supabase migration CI:** [`.github/workflows/supabase-ci.yml`](../../.github/workflows/supabase-ci.yml)
* **FHIR fixture validator:** [`.github/workflows/fhir-validate.yml`](../../.github/workflows/fhir-validate.yml)
* **Full E2E (nightly/manual):** [`.github/workflows/e2e-full.yml`](../../.github/workflows/e2e-full.yml)
* **Cross-repo mirror:** [`.github/workflows/mirror-development-to-encore-lovable.yml`](../../.github/workflows/mirror-development-to-encore-lovable.yml)

## Tiered CI Structure

### Tier 1: Fast PR checks (`pull_request`)

`pr-guardrails.yml` runs first, then `build.yml` runs in parallel:

0. **`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`
   * `npm run audit:package-boundaries`
   * `npm run audit:microfrontends`
   * `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)
   * `npm run check:dead-code:ci` (non-blocking)
   * `npm run check:deps` (non-blocking)

### 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:

```bash theme={null}
npm run validate
```

Recommended pre-merge confidence:

```bash theme={null}
npm run validate:full
npm run test:baseline:smoke
```

For DB-related changes:

```bash theme={null}
npm run db:schemas:lint
npm run test:rls:smoke
```

## 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.

## Related Docs

* [`docs/testing/TESTING_SETUP_AND_RUN.md`](../testing/TESTING_SETUP_AND_RUN.md)
* [`docs/development/RLS_CI_CD_GUIDE.md`](./RLS_CI_CD_GUIDE.md)
* [`docs/development/DEPENDENCY_SECURITY.md`](./DEPENDENCY_SECURITY.md)
* [`docs/development/VERCEL_VITE_NODE_GUARDRAILS.md`](./VERCEL_VITE_NODE_GUARDRAILS.md)

# 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

* **Build gate:** [.github/workflows/build.yml](../../.github/workflows/build.yml) — runs on `push` and `pull_request` to `main` and `feature/**`.

## 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`, `check:dead-code:ci`, `check:deps`
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:

```bash theme={null}
npm run validate
```

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](../testing/TESTING_SETUP_AND_RUN.md) for E2E and env requirements.

## Non-Blocking Gate Tightening Plan

Steps 8 above (`check:slop:ci`, `check:dead-code:ci`, `check:deps`) currently run with `|| true` to avoid blocking CI while baselines are established. These should be converted to blocking gates progressively:

| Gate                        | Current               | Target        | When to Tighten                    | How                                      |
| --------------------------- | --------------------- | ------------- | ---------------------------------- | ---------------------------------------- |
| `check:slop:ci`             | `\|\| true` (warning) | Blocking      | When slop count \< 10              | Remove `\|\| true` from `build.yml` step |
| `check:deps`                | `\|\| true` (warning) | Blocking      | When known dep issues are resolved | Remove `\|\| true`                       |
| `check:dead-code:ci`        | `\|\| true` (warning) | Blocking      | When dead code count \< 50         | Remove `\|\| true`                       |
| `audit-compliance-evidence` | Manual only           | Weekly CI job | Now                                | Add to scheduled workflow                |

**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

## Related docs

* [RLS\_CI\_CD\_GUIDE.md](./RLS_CI_CD_GUIDE.md) — RLS tests in CI and local parity
* [DEPENDENCY\_SECURITY.md](./DEPENDENCY_SECURITY.md) — audit, overrides, Dependabot
* [VERCEL\_BUILD\_IMPROVEMENT\_PLAN.md](./VERCEL_BUILD_IMPROVEMENT_PLAN.md) — context for the build workflow header
* [VERCEL\_VITE\_NODE\_GUARDRAILS.md](./VERCEL_VITE_NODE_GUARDRAILS.md) — Node 22+ baseline, Vite 8/Rolldown, Vercel build pitfalls
* docs/governance/index.md — governance entry point and all gate documentation