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

62 lines
8.5 KiB
Markdown
Raw Normal View History

# ZitPlane P05-CI-03 — Backend Runtime Final Acceptance
**Date:** 2026-11-22
**Status:** BACKEND-ONLY CI ACCEPTANCE CLOSED/PASS — Run #86 SUCCESS; result documented and approved Git sync.
**Baseline / Gitea main:** `485755800504a7dea6e4c303e6b39ec9cc610b54`
**Prior CI:** [Run #83](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/83), tested `c27fe3d`; three jobs PASS (Account Portal, Login V2 including 1219 unit tests, High/Critical security gate), backend FAIL when proxy attempted to publish occupied host port 8080.
## Exact scope lock
**Allowed writes:** optional **new** `.gitea/workflows/p05-backend-acceptance.yml`; narrow `.gitea/workflows/p05-ci.yml` if justified; focused `tests/ci/**` (including `compose.portless.override.yaml`, `oidc_discovery.py`, README/MINIFEST), `.gitea/**/README.md` and `MINIFEST.md`; `notes/**`, `project/**`, related `docs/**`, root `README.md`/`MINIFEST.md` only as necessary.
**Strict read-only:** `core/backend/zitadel/**`, `deployment/docker/compose.backend.dev.yaml`, `auth/ui/v2/**`, `users/ui/**`, manifest/lockfiles, current UI/auth/session logic, production configuration and unrelated files. Existing untracked `AI_INSTRUCTIONS.md` must remain untouched.
**Execution:** one focused **backend-only** isolated Gitea Actions CI run after source commit/push; **no local tests/builds/dev servers/Docker**, no re-run of accepted Account/Login unit suites; no production deployment, release or real users/secrets.
## Verified pre-change root cause and constraints
1. Run #83 backend #174: Git Alpine pre-checkout and Docker daemon preflight PASS; P02 Python stdlib unit 3/3 PASS; PostgreSQL, official ZITADEL API v4.20.4, prebuilt Login v4.20.4 healthy. Traefik failed before health/discovery: `port 8080 is already allocated`. Always-cleanup removed CI-owned containers, volumes and network.
2. Post-run `tests/ci/compose.portless.override.yaml` uses Docker Compose supported `ports: !reset []` on `proxy`; P05-CI-02 inserted it on all 10 Compose references with effective-config `proxy.ports` guard. **This override has never been executed in CI**.
3. P02 developer Compose has fixed `zitplane-backend-dev-internal` network and local-only `127.0.0.1:8080:80` port. The CI must refuse any existing fixed network or competing project; never touch shared Docker stacks. CI-specific override must remove host port entirely.
4. Existing `tests/ci/oidc_discovery.py` checks synthetic rejection cases plus real `/debug/ready`, issuer/origin discovery, JWKS (nonempty key list) through internal Docker network and host `localhost:8080`. No real login, Admin Console, MFA or callback E2E acceptance is possible in this phase.
## Implementation plan (prior to source changes)
A. Add **backend-only manual** `.gitea/workflows/p05-backend-acceptance.yml` to avoid repeated Account/Login/Security jobs; use existing verified Alpine Git checkout prerequisite and Docker CLI capability preflight, previous P02 focused backend helper tests, guarded fixed network/project name, and P05 portless Compose overlay. Hard-fail before starting containers unless resulting proxy has no host ports.
B. Run disposable Compose `up -d --wait`; verify all four containers (`postgres`, `zitadel-api`, `zitadel-login`, `proxy`) are present and healthy/running as appropriate. Write a synthetic marker into the disposable Postgres default `postgres` DB, restart database, wait for health and confirm marker persists; probe readiness, exact local issuer metadata and public JWKS from an ephemeral probe container attached to the *new CI-owned network*.
C. Always tear down **only the run's Compose project/volumes**, delete generated local credentials; verify no run-owned containers, volumes or fixed network remain. If failure/cleanup incomplete, report exact blocker, never claim PASS.
D. Update manifest/README, `project/` function/file/CI history and `docs/` operator status. Audit exact staged paths/secrets. Commit and push source to Gitea main, dispatch **one** backend-only run, capture its actual terminal job logs.
E. Document exact CI SHA, PASS/FAIL/BLOCKED, remedy/outstanding risks and acceptance; do one final documentation-only commit/push with exact remote SHA. No rerun even if a focused defect is found. After closure provide next precise Scope Lock, concise implementation plan, and copy-ready approval.
## Acceptance definitions
Backend PASS only if effective Docker config is portless, four services reach the intended state, Postgres restart retains synthetic marker, real local ZITADEL ready + OIDC discovery + JWKS and negative test cases all PASS, and CI-owned network/volumes/container cleanup verified. Else mark FAILED/BLOCKED and preserve real source/log evidence.
**Not in scope:** real OIDC authorized login/callback, Admin Console human login, MFA/SSO, dependency Moderate fixes (18 Login + 1 Account package), UI redesign or production TLS/Coolify.
## Implementation, exact Gitea evidence and closure — 2026-11-22
**Source commit pushed before dispatch:** `03fb58954dec886128a4011b6121754cbcdd79ff`.
**Single focused Gitea run:** [#86](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/86), event `workflow_dispatch`, branch `main`, tested SHA `03fb58954dec886128a4011b6121754cbcdd79ff`. Started 2026-11-22 13:47:58 UTC, completed 13:48:56 UTC, **overall SUCCESS**. Exactly one backend-only job (#184); all four job steps completed SUCCESS, including always-run cleanup. No Account/Login/Security builds or full suites rerun.
**Implemented files:** `.gitea/workflows/p05-backend-acceptance.yml` manual job; `tests/ci/backend_acceptance.sh` for ownership preflight/config, health, disposable Postgres marker and OIDC checks; `tests/ci/backend_cleanup.sh` for guarded disposal and explicit no-leftovers verification. Existing `compose.portless.override.yaml` and `oidc_discovery.py` reused without modification. Backend core, P02 Compose, Login V2/Account Portal, production config and package/lock versions unchanged. README/MINIFEST/project/docs updated in the approved scope.
### Terminal CI evidence
| Check | Result | Log marker/observable evidence |
| --- | --- | --- |
| Alpine Git + checkout, Docker/Compose preflight | **PASS** | Job #184 first two steps SUCCESS; `ZITPLANE_DOCKER_DAEMON_PREFLIGHT_PASS`; Docker 29.9.3 / Compose v5.7.2 |
| P02 backend static regression | **PASS** | 3/3 focused `test_backend_dev.py` cases; `ZITPLANE_P02_BACKEND_CONTRACTS_PASS` |
| Portless CI effective Compose | **PASS** | `ZITPLANE_CI_PORTLESS_CONFIG_PASS`; no host proxy ports; occupied 8080 irrelevant |
| Four services | **PASS** | PostgreSQL, ZITADEL API, prebuilt Login V2 healthy; Traefik proxy running/healthy; four `ZITPLANE_SERVICE_RUNNING_PASS` entries and `ZITPLANE_FOUR_SERVICES_READY_PASS` |
| Postgres restart persistence | **PASS** | Disposable marker table created, synthetic row inserted, container restarted, row reread; `ZITPLANE_POSTGRES_RESTART_PERSISTENCE_PASS` |
| OIDC negative security contracts | **PASS** | `ZITPLANE_OIDC_NEGATIVE_CONTRACTS_PASS` rejects mismatched issuer/unsafe endpoint/JWKS fixtures |
| Real backend ready, OIDC issuer/discovery, public JWKS | **PASS** | `ZITPLANE_BACKEND_READY_PASS`, `ZITPLANE_OIDC_DISCOVERY_PASS` with `http://localhost:8080`, `ZITPLANE_OIDC_JWKS_PASS`, `ZITPLANE_BACKEND_OIDC_READY_DISCOVERY_JWKS_PASS` |
| Always owned-resource cleanup | **PASS** | Compose down -v removed owned containers, volumes and fixed network; `ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS`; cleanup workflow step SUCCESS |
**Verdict:** P05-CI-03 backend-only **ACCEPTED/PASS**. No local PC builds/tests/Docker/dev server were executed and no real-user/production deployment was touched. One Gitea cycle, not a repeated loop. All credentials were generated temporarily inside the runner, not committed or logged.
**Still outside backend acceptance:** full authorized OIDC client/callback/positive portal session, Admin Console human sign-in, MFA/passkeys, federated logout, production HTTPS/Coolify and security patching of the 18 Moderate Login advisory records plus the 1 Moderate affected Account Portal `next` package. High/Critical audit gates passed in earlier Run #83; moderate issues remain OPEN. Future phases: targeted dependency-only P05-SEC-01, then isolated authenticated user P05-OIDC-01 with separate scope.
**Source/security audit:** initial CI-source commit had 22 approved files, 0 unauthorized paths, 0 staged secret files, 0 broken checked relative links, 724/724 Git-tracked source paths inventoried and all five affected directory manifests exact. The final documentation-only follow-up commit records Run #86 terminal results; its SHA is NOT the tested CI source SHA.