Files
ZitPlane/docs/P05-CI-03.md
T

3.7 KiB

P05-CI-03 — Backend-only Gitea CI Acceptance

Date: 2026-11-22 Approved baseline: 485755800504a7dea6e4c303e6b39ec9cc610b54 Status: Source prepared; no P05-CI-03 workflow run yet.

Objective and user-visible effect

Verify the existing official ZITADEL v4.20.4 + PostgreSQL + prebuilt Login V2 + Traefik local development stack in an isolated Gitea Actions runner. This is NOT an application feature release or an authentication redesign. It does not start the app on your PC, configure public domains, modify credentials/users, or deploy anything.

How to launch the backend-only workflow

In Gitea vibtools/ZitPlane, open Actions → ZitPlane P05-CI-03 Backend Acceptance → Run workflow → main. Only one manual workflow_dispatch is authorized for this phase. The new workflow is .gitea/workflows/p05-backend-acceptance.yml; prior Account and Login V2 build suites are deliberately not rerun.

The runner needs its registered ubuntu-latest label, a functional Docker daemon/socket, Docker Compose v2 with support for !reset, access to pinned image registries and enough storage/time for four images. Do not run it on shared hosts with existing zitplane-backend-dev-internal network or an identical CI Compose project name.

Required verification

  1. Git checkout / Docker Engine / Compose preflight; refuse existing named network, project containers, or named volumes.
  2. Generate fresh disposable local secrets in ignored .env. Merge the read-only P02 Compose with tests/ci/compose.portless.override.yaml; inspect effective proxy config to ensure no host port publishing, including TCP 8080.
  3. Start and wait for PostgreSQL, ZITADEL API, prebuilt Login V2 and Traefik. Confirm first three healthy and proxy running.
  4. Write synthetic marker in disposable Postgres postgres database; restart Postgres; check marker survives after health recovery.
  5. From a disposable probe container within the CI-owned Docker network, check /debug/ready, exact local issuer http://localhost:8080, OIDC discovery endpoint URLs and a nonempty JWKS. Run malformed issuer/JWKS negative fixtures.
  6. In a separate always-run step, stop only CI-owned Compose project, remove its disposable volumes, then check that no CI network/container/volume remains. Report any cleanup failure instead of claiming success.

Expected markers: ZITPLANE_CI_PORTLESS_CONFIG_PASS, ZITPLANE_FOUR_SERVICES_READY_PASS, ZITPLANE_POSTGRES_RESTART_PERSISTENCE_PASS, ZITPLANE_OIDC_NEGATIVE_CONTRACTS_PASS, ZITPLANE_BACKEND_OIDC_READY_DISCOVERY_JWKS_PASS, ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS.

Do not claim backend acceptance unless each required check actually executes and passes. Before the run, all are PENDING.

Out of scope / known boundaries

Account Portal real authenticated login/callback and protected positive session; ZITADEL Admin Console human login, MFA, passkey, global SSO logout; Moderate dependency remediation (18 Login records plus 1 Account affected package); production ZITADEL, Coolify, DNS, TLS, backups and user data. Existing P02 developer Compose, Login V2 source and Account Portal must remain unchanged.

Actual acceptance ledger

PENDING: After the single Gitea run, record run ID, tested source SHA, job conclusion, each marker, Docker service state, Postgres persistence, exact issuer/JWKS results, cleanup outcome and reproduced blockers. If any gate fails, label acceptance BLOCKED/FAILED and propose a focused next phase. Gitea workflow source-only changes or historical P05 runs are not proof of this phase.

Developer details: project/CI-ARCHITECTURE.md. Pre-change plan and final log: notes/P05-CI-03.md.