familysync/.planning/phases/08-gitea-ci/08-02-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
08-gitea-ci	02	execute	2	08-01	.gitea/workflows/ci.yml	false	CI-01	truths artifacts key_links Opening or updating a PR targeting main triggers ci.yml A fast-checks job runs lint + typecheck (both apps) + PWA unit tests in parallel with the API job An API job stands up a MariaDB 11 service container (or docker-run fallback), waits for real readiness via healthcheck.sh --connect --innodb_initialized, runs drizzle-kit migrate, then runs the DB-backed API test suite Both jobs gate the PR — a failure in either blocks merge once required-checks branch protection is configured path provides contains .gitea/workflows/ci.yml PR-triggered fast-checks + API-integration jobs pull_request from to via pattern .gitea/workflows/ci.yml (api job) mariadb:11 service DB_HOST + drizzle-kit migrate + vitest healthcheck.sh --connect --innodb_initialized from to via pattern .gitea/workflows/ci.yml (fast-checks job) pnpm scripts run: pnpm lint / typecheck / pwa test pnpm (-r )?(lint|typecheck)

Create the single CI workflow file `.gitea/workflows/ci.yml` and populate it with the two PR-gating jobs that need no browser: a fast-checks job (lint + typecheck both apps + PWA unit tests) running in parallel with an API job that runs the DB-backed API test suite against a MariaDB service container. This delivers the non-harness half of CI-01 (ROADMAP criteria 1 + 2) and Pitfall 11 (MariaDB-11 readiness).

Purpose: Fast PR feedback (D-03 — a lint failure does not wait behind the heavier jobs) plus a reliable cold-start API-integration gate. Uses the runner mode answer from 08-01-SUMMARY to choose service-container vs docker-run DB bring-up.

Output: .gitea/workflows/ci.yml containing fast-checks and api jobs gated on pull_request → main.

CRITICAL CONTEXT — read 08-01-SUMMARY first for the runner-mode fork:

• If 08-01 found DOCKER-executor mode: use services: mariadb: with DB_HOST: mariadb (08-RESEARCH Pattern 1).
• If 08-01 found HOST-executor mode: use a docker run -d mariadb:11 -p 3306:3306 step + explicit readiness loop with DB_HOST: 127.0.0.1 (08-RESEARCH Pattern 2). Service containers do NOT work in host mode (nektos/act#2711).

<execution_context> @$HOME/.claude/gsd-core/workflows/execute-plan.md @$HOME/.claude/gsd-core/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/08-gitea-ci/08-RESEARCH.md @.planning/research/PITFALLS.md @.planning/phases/08-gitea-ci/08-01-SUMMARY.md

<artifacts_this_phase_produces>

• .gitea/workflows/ci.yml (NEW — this plan creates it; Plans 03/04 extend it) </artifacts_this_phase_produces>

<interface_context> Confirmed repo facts the executor MUST honor (do not re-derive):

• Root scripts: lint = pnpm -r lint, typecheck = pnpm -r typecheck, test = pnpm --filter @familysync/api test (= vitest run), PWA unit = pnpm --filter @familysync/pwa test.
• IMPORTANT — lint is currently a NO-OP: no package defines a lint script and ESLint is not installed, so pnpm lint (pnpm -r lint) prints ERR_PNPM_RECURSIVE_RUN_NO_SCRIPT but EXITS 0 and passes. Run pnpm lint as the documented command (satisfies CI-01's "lint" gate literally); do NOT add ESLint config — wiring lint is out of this phase's scope (CI-plumbing-only boundary). Note this in the SUMMARY so it is not mistaken for a bug.
• ALL apps/api tests live in apps/api/tests/ and apps/api/test/setup.ts truncates DB tables in an afterEach (it swallows errors if no DB). So pnpm --filter @familysync/api test REQUIRES a real MariaDB — the API "unit" and "integration" tests are one DB-backed command. The fast-checks job therefore runs only the PWA unit tests (no DB); the API job owns all API tests (with DB).
• apps/pwa unit tests (pnpm --filter @familysync/pwa test) need NO DB.
• DB env var names (from apps/api/src/db/client.ts + drizzle.config.ts): DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME. Migrations: pnpm --filter @familysync/api db:migrate (= drizzle-kit migrate). NEVER db:push (unsafe on MariaDB — project memory).
• packageManager is pnpm@11.5.1; no .nvmrc/engines pin → pin Node 22 via actions/setup-node@v4 + corepack enable pnpm.
• Workspace is apps/* only (no packages/shared despite CLAUDE.md mention) — pnpm -r spans 2 packages. </interface_context>

Task 1: Create ci.yml with the fast-checks job .gitea/workflows/ci.yml - .planning/phases/08-gitea-ci/08-01-SUMMARY.md (runner-mode fork answer; cache usable y/n) - .planning/phases/08-gitea-ci/08-RESEARCH.md (§Architecture Patterns job topology; §Standard Stack action versions; Pitfall 7 cache) - package.json (root scripts: lint, typecheck, test:e2e) - apps/pwa/package.json (pwa test script) Create `.gitea/workflows/ci.yml`. Header `name: CI`. Triggers: `on: { pull_request: { branches: [main] }, push: { branches: [main] } }` — both events declared now (the publish job in Plan 04 consumes the push event; the PR jobs filter to `pull_request`).

Add a workflow-level `env: { MILESTONE: v1.1 }` (per D-04; Plan 04 uses it).

Add the `fast-checks` job: `runs-on: self-hosted`, guarded `if: github.event_name == 'pull_request'`. Steps:
  1. `uses: actions/checkout@v4`
  2. `uses: actions/setup-node@v4` with `node-version: '22'`
  3. `run: corepack enable pnpm`
  4. Optional pnpm-store cache via `actions/cache@v4` ONLY if 08-01-SUMMARY reported cache works; otherwise OMIT the cache step entirely (do not add a hanging step). If included, wrap with `continue-on-error: true` (Pitfall 7).
  5. `run: pnpm install --frozen-lockfile`
  6. `run: pnpm lint` (no-op per interface_context, but the documented lint gate)
  7. `run: pnpm typecheck` (= `pnpm -r typecheck` → tsc --noEmit in both apps incl. pwa tsconfig.e2e.json)
  8. `run: pnpm --filter @familysync/pwa test` (PWA unit tests — no DB needed)
Do NOT run `pnpm test` here (that is the DB-backed API suite — it belongs in the api job).

test -f .gitea/workflows/ci.yml && grep -q "pull_request" .gitea/workflows/ci.yml && grep -q "node-version: '22'" .gitea/workflows/ci.yml && grep -q "pnpm typecheck" .gitea/workflows/ci.yml && grep -q "@familysync/pwa test" .gitea/workflows/ci.yml && echo FASTCHECKS_OK ci.yml exists with a pull_request-gated fast-checks job pinning Node 22, enabling pnpm via corepack, running lint + typecheck + PWA unit tests; no DB-backed `pnpm test` in this job. Task 2: Add the API job (MariaDB service + migrate + DB-backed tests) .gitea/workflows/ci.yml - .planning/phases/08-gitea-ci/08-01-SUMMARY.md (Docker vs host mode — selects services: vs docker run; MariaDB hostname) - .planning/phases/08-gitea-ci/08-RESEARCH.md (§Pattern 1 service container, §Pattern 2 host-mode fallback, §Pattern 4 Drizzle migrate; Pitfall 1 host-mode, Pitfall 2 mariadb healthcheck) - apps/api/test/setup.ts (confirms API tests need a real DB) - docker-compose.yml (MariaDB 11 healthcheck reference: healthcheck.sh --connect --innodb_initialized) Add an `api` job to ci.yml: `runs-on: self-hosted`, `if: github.event_name == 'pull_request'` (runs in PARALLEL with fast-checks — D-03; no `needs:` linking them).

DB bring-up — branch on 08-01-SUMMARY runner mode:
  - DOCKER mode: declare `services: mariadb:` with `image: mariadb:11`, env `{ MARIADB_ROOT_PASSWORD: root, MARIADB_DATABASE: familysync, MARIADB_USER: familysync, MARIADB_PASSWORD: testpass }`, and `options: >- --health-cmd="healthcheck.sh --connect --innodb_initialized" --health-interval=10s --health-timeout=5s --health-retries=10 --health-start-period=30s`. Set job `env.DB_HOST: mariadb`. (08-RESEARCH Pattern 1.) `--health-start-period=30s` because MariaDB 11 InnoDB init is slow (A9).
  - HOST mode: instead, a first step `docker run -d --name mariadb -e MARIADB_ROOT_PASSWORD=root -e MARIADB_DATABASE=familysync -e MARIADB_USER=familysync -e MARIADB_PASSWORD=testpass -p 3306:3306 mariadb:11`, then an explicit readiness-loop step using `docker exec mariadb healthcheck.sh --connect --innodb_initialized` with a ~90s deadline (08-RESEARCH Pattern 2). Set `env.DB_HOST: 127.0.0.1`.

Regardless of mode, set job-level `env`: DB_PORT: 3306, DB_USER: familysync, DB_PASSWORD: testpass, DB_NAME: familysync (throwaway creds — NEVER reuse production secrets; T-08-03).

Even in Docker mode (where options: auto-waits), add an explicit readiness step BEFORE migrate: a loop that polls `healthcheck.sh --connect --innodb_initialized` (in Docker mode, via a one-shot `mariadb:11` client container or `mysql -h $DB_HOST ... -e "SELECT 1"`) with a deadline — Pitfall 11: healthy-in-Docker ≠ accepting-connections, and the cold-first-run reliability is ROADMAP criterion 2. Never use `mysqladmin ping` (removed in MariaDB 11).

Then steps:
  - `uses: actions/checkout@v4`; `uses: actions/setup-node@v4` (node 22); `corepack enable pnpm`; `pnpm install --frozen-lockfile`.
  - `run: pnpm --filter @familysync/api db:migrate` (drizzle-kit migrate — applies repo SQL; NEVER db:push). Pass DB_* env.
  - `run: pnpm --filter @familysync/api test` (the full DB-backed API suite). Pass DB_* env.

Reuse the same cache decision as Task 1 (include only if 08-01 confirmed cache works).

grep -q "mariadb:11" .gitea/workflows/ci.yml && grep -q "healthcheck.sh --connect --innodb_initialized" .gitea/workflows/ci.yml && ! grep -q "mysqladmin" .gitea/workflows/ci.yml && grep -q "db:migrate" .gitea/workflows/ci.yml && ! grep -q "db:push" .gitea/workflows/ci.yml && grep -q "@familysync/api test" .gitea/workflows/ci.yml && echo APIJOB_OK ci.yml has a parallel pull_request-gated api job that brings up MariaDB 11 (services: or docker run per runner mode), waits for real readiness via healthcheck.sh (never mysqladmin), runs drizzle-kit migrate (never push), and runs the DB-backed API test suite with throwaway creds. Task 3: Verify fast-checks + api jobs on a PR ci.yml with parallel fast-checks + api jobs (Tasks 1–2), exercised by opening a PR from gsd/phase-08-gitea-ci → main. 1. Push the branch and open a PR targeting `main`. 2. In Gitea → Actions, confirm BOTH `fast-checks` and `api` jobs are triggered and run in parallel. 3. Confirm the api job passes on a COLD first run (ROADMAP criterion 2) — not only on re-run. If it fails with ECONNREFUSED to 3306, the MariaDB readiness wait is too short; lengthen the deadline / start-period (Pitfall 11) rather than re-running. 4. Confirm fast-checks runs lint (no-op), typecheck, and PWA unit tests green. 5. (Operator, optional but recommended) Configure branch protection on `main` → required status checks include these jobs, so a failure actually blocks merge (08-VALIDATION Manual-Only). Type "W1 green" once both jobs pass on a cold PR run, or paste the failing log.

<threat_model>

Trust Boundaries

Boundary	Description
PR head → CI runner	PR-triggered job runs untrusted branch content on operator infra
Test DB creds → job env	Throwaway creds in CI env; must not be production secrets

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-08-03	Information Disclosure	MariaDB creds in job env	mitigate	Use throwaway creds (familysync/testpass, root/root) scoped to the ephemeral service container only; NEVER reference production DB_PASSWORD or any repo secret in these jobs (08-RESEARCH Security Domain).
T-08-04	Tampering	drizzle-kit against CI DB	mitigate	Use db:migrate (applies committed SQL) exclusively; db:push is forbidden (emits destructive TRUNCATE diff on MariaDB — project memory drizzle-mariadb-push-unsafe). Verified by grep gate (! grep db:push).
T-08-05	Denial of Service	cold-start readiness race	mitigate	Explicit healthcheck.sh readiness loop before migrate (Pitfall 11) so the gate is reliable on first run, not flaky.
</threat_model>

- ci.yml passes both Task grep gates (service container + readiness + migrate-not-push; fast-checks node-pin + typecheck + pwa test). - PR run shows fast-checks ∥ api in parallel; api green on cold first run. - No production secret referenced in either job.

<success_criteria>

• CI-01 (non-harness half): PR to main runs lint + typecheck (both apps) + unit tests + API integration vs MariaDB service container; failures gate merge (ROADMAP criteria 1 + 2).
• Pitfall 11 honored: healthcheck.sh --connect --innodb_initialized readiness, never mysqladmin; reliable cold-start.
• One workflow file (D-03), parallel event-gated jobs. </success_criteria>

Create `.planning/phases/08-gitea-ci/08-02-SUMMARY.md` when done. Record: the chosen DB bring-up path (services vs docker-run), final readiness timeout values, whether cache was enabled, and the lint-is-a-no-op note.