Files
ZitPlane/project/CI-ARCHITECTURE.md
T

8.0 KiB

ZitPlane P05-CI-01 - Gitea Actions verification architecture

Status: P05-CI-01 Run #81 overall FAIL; P05-CI-02 Run #83 3 PASS / 1 FAIL (Account, Login, Security pass; backend proxy host-port collision). CI-only portless source correction after Run #83 remains unverified. Full OIDC and runtime acceptance pending. Approved baseline: 7ecf53169776cc7f08af3dde6fe4b4492acf3ea1 (2026-11-22).

Exact job map

Job Runner / source What PASS means Not covered
account ubuntu-latest, node:22-bookworm; users/ui/ Structural guard + npm ci, tsc --noEmit, Next standalone production build Real login/redirect, live Account Portal
login ubuntu-latest, node:22-bookworm; auth/ui/v2/ Frozen pnpm install, Nx proto/client/login build and original Login unit suite Interactive admin/password/MFA/SSO integration
security ubuntu-latest, node:22-bookworm NPM and pnpm production dependency advisories at HIGH+ thresholds triaged by runner registry License/legal or full application security proof
backend ubuntu-latest, node:22-alpine; deployment/docker/compose.backend.dev.yaml read-only Docker daemon preflight, Python helper contracts, disposable ZITADEL stack, readiness, OIDC discovery and JWKS Portal OIDC callback, MFA, live account session, production TLS

All jobs use the previously seen Gitea standard ubuntu-latest runner label; no separate runner is created or installed. A failed runner capability is a BLOCKED gate, never a PASS. Docker job must not run from an untrusted pull request; the workflow is workflow_dispatch only.

Dependency/root cause fixes

  • auth/ui/v2/pnpm-workspace.yaml has only the 3 actually imported packages. P03's original pnpm-lock.yaml retains exact packages:/snapshots: resolution graph; 4 missing-upstream importers were removed, 4 present importers retained.
  • Account Portal package-lock v3 generated using local npm install --package-lock-only --ignore-scripts --no-audit --no-fund --engine-strict, not an install/test/build. Root package manifest matches lock manifest.
  • Login CI sets up pinned pnpm 10.30.3, runs --frozen-lockfile and the upstream Nx dependency graph; no upstream UI/auth logic was modified.
  • Account CI uses npm ci only from committed lock, plus TS + production Next build. No automatically loosened package versions or npm install fallback.
  • Security jobs audit dependency advisory metadata on the runner. Any failure is reported verbatim with severity/package/version; no blind package updates.

Disposable backend safety and behavior

The P02 Compose has a fixed named network zitplane-backend-dev-internal and loopback-only 127.0.0.1:8080. CI refuses to start if that network already exists. It generates independent random .env in runner checkout and uses unique Compose project name zitplane-p05-${GITHUB_RUN_ID}. A marker is written only after the network absence check; cleanup uses that exact Compose project, deletes its ephemeral volumes, and removes its temporary credentials. It never connects to auth.vib.tools, account.vib.tools or any production database.

tests/ci/oidc_discovery.py probes ready/discovery/JWKS inside disposable Docker network only, avoiding exposing admin PATs. OIDC full user-session acceptance is explicitly NOT VERIFIED: P05 does not provision a disposable confidential OIDC app, fake user or Session API script. A 200 readiness/discovery alone does not constitute user login, MFA, PKCE callback, protected account route or logout acceptance.

Future gates

  1. Document actual Gitea runner job results and exact failure/line in notes/P05-CI-01.md and docs/P05-CI-01.md.
  2. If any job fails, keep immutable logged evidence; fix only reproduced narrow defects with separate approval if outside P05 Scope Lock.
  3. Provide disposable OIDC client/user provisioning and Account Portal auth/session lifecycle tests in a narrow separately approved integration phase.
  4. Production Docker/Coolify/TLS and DNS are out of scope.

Reference: notes/P05-CI-01.md, docs/PHASES.md, .gitea/workflows/p05-ci.yml, tests/ci/.

P05-CI-02 Narrow Auth.js and CI additions

  • users/ui/src/auth.ts callbacks.session: const subject: string = typeof token.zitadelSubject === "string" ? token.zitadelSubject : ""; explicitly narrows the JWT claim. Session still sets id only when subject nonempty and OIDC access-token expiry is in the future. users/ui/src/types/next-auth.d.ts was not changed. This addresses Run #81's TS2345 (user.id: {}) without a cast or altered PKCE/state/nonce.
  • tests/ci/account_negative.py + Account job: anonymous identity API 401/no-store and protected route redirect; no fake logged-in account. tests/ci/oidc_discovery.py: issuer/origin/JWKS negative contracts plus actual disposable ready/discovery/JWKS. Tests are CI-only.
  • tests/ci/advisory_triage.py: parse live npm/pnpm registry JSON into advisory IDs, package, affected range, patch availability. Prior high/critical failure threshold maintained; no dependency versions changed.
  • Backend CI: after safe Docker/network preflight and startup, write one marker in disposable Postgres database postgres, restart its container, verify marker persists and ZITADEL becomes ready, then test OIDC discovery/JWKS. Always cleanup only the current CI Compose project and its volumes; failure must remain visible.
  • Corrected Alpine Git checkout from P05-CI-01 is exercised by the new run. Fixed name zitplane-backend-dev-internal is a known isolation limitation: existing network triggers fail-closed instead of reuse.
  • No full interactive user login callback, MFA, Admin Console user session or production TLS verification; separate future scope.

Verified Gitea Run #81 and source follow-up

Initial dispatched commit 42b79362c13b9dbb07f85a58ad278742d91b1f5b. Two PASS: Login V2 frozen reproducible install, production build and 1219/1219 upstream unit tests; dependency advisory gate at high/critical only (18 moderate findings outstanding). Two FAIL: Account Portal TS2345 Auth.js session callback type mismatch; Alpine backend actions/checkout fallback Not found because Git missing before checkout. The Docker runtime and full interactive OIDC flow were not executed.

Pre-checkout Git install inserted in the backend workflow after this failed run; this is only a source fix until a future run actually passes. Reference docs/P05-CI-01.md for job numbers and notes/P05-CI-01.md for the next phase defect IDs. There was no second CI run or local test.

P05-CI-02 Run #83 final evidence and post-run portless exception

Gitea Run #83 on SHA c27fe3d3234d16375b962b88014cdd8733ab2fb4: three job PASS (Account npm ci/typecheck/build/anonymous 401 and protected redirect; Login V2 frozen/Nx build + 1219 tests; HIGH/CRITICAL security audit with 18 Moderate Login records and 1 Moderate Account package); Docker job FAIL after Postgres, ZITADEL API and prebuilt Login V2 reported healthy. Traefik proxy attempted to bind occupied runner TCP 8080. Always cleanup removed only job-owned containers, network and volumes; persistence and OIDC discovery were not reached.

Only after that run, a P05-scoped CI overlay at tests/ci/compose.portless.override.yaml set proxy.ports: !reset [], as documented by Docker Compose: https://docs.docker.com/reference/compose-file/merge/#reset-value. Every backend workflow Compose call now includes this override; a fail-closed effective-config probe rejects any inherited host port. The P02 Compose and application logic remain untouched. Post-run override has not been CI tested. New exact Gitea main commit is documentation/source only and must not be described as the tested Run #83 SHA.

Unresolved: one separately approved isolated backend re-verification cycle for the portless override, Postgres restart persistence and live OIDC/JWKS; distinct disposable authenticated OIDC/client/user + MFA E2E; targeted dependency-only security remediation of Moderate findings (no upgrades in P05-CI-02).