ci: add isolated backend-only P05 runtime acceptance

This commit is contained in:
Vib Tools committed 2026-11-22 05:47:38 -08:00
1 parent 4857558005
commit 03fb58954d
22 files changed
+370 -27

No files matched your search

+1
View File
@@ -11,6 +11,7 @@ This is the **developer-focused implementation history**. `notes/CHANGELOG.md` i
| 2026-11-22 | DOCS-01 | Documentation governance; developer architecture, reviewed first-party function/file/page mapping and 701-path source inventory; user manual/setup/status/troubleshooting | Documentation complete; manifest/link/source-scope audit PASS; `notes/DOCS-01.md`, local commit SHA via Git history |
| 2026-11-22 | P05-CI-01 | `.gitea/workflows/p05-ci.yml`, `tests/ci/**`, Account npm lock, Login pnpm importer reconciliation and in-scope Alpine Git checkout correction | Run #81 overall FAIL; 2 jobs PASS, 2 FAIL; Login 1219/1219 tests PASS, Account TS2345 and Docker checkout blocked; `notes/P05-CI-01.md` |
| 2026-11-22 | P05-CI-02 | Type-safe Auth.js subject narrowing, Account anonymous negative tests, Login regression, structured advisory triage and CI-only portless Docker override | Run #83: 3 PASS/1 FAIL; Docker proxy 8080 collision, cleanup PASS, portless fix unverified; see `notes/P05-CI-02.md` |
| 2026-11-22 | P05-CI-03 | Dedicated manual backend-only CI acceptance, guarded disposable Compose, persistence/ready/JWKS probes and owned-state cleanup | Source implemented, Gitea CI run pending; `notes/P05-CI-03.md` |
## Required entry for each future change
+15
View File
@@ -60,3 +60,18 @@ Gitea [Run #83](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/83) on SHA `c
**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).
## P05-CI-03 — backend-only disposable acceptance
This is a **separate** `.gitea/workflows/p05-backend-acceptance.yml` triggered manually on Gitea `main`. It does not schedule the previous Account/ Login V2/ security jobs again.
- A short Alpine Git prerequisite precedes `actions/checkout@v4`. After checkout, only Python 3 stdlib and Docker CLI/Compose are installed in CI (not on the developer PC).
- `tests/ci/backend_acceptance.sh` accepts only a numeric `GITHUB_RUN_ID`; derives a unique Compose project `zitplane-p05-<run-id>`; refuses existing hardcoded P02 network, same project containers or volumes. An existing local `.env` or ownership marker also causes fail-closed.
- The original `deployment/docker/compose.backend.dev.yaml` is read-only; `tests/ci/compose.portless.override.yaml` removes `proxy.ports` and JSON merged configuration explicitly rejects host publishing. This isolates the shared Actions Docker host from an occupied TCP 8080.
- After source-level P02 unit contracts (CI only) and fresh ignored `.env` creation, a marker `.p05-ci-owned` is created **only after** all collision/config checks. Then `docker compose up -d --wait` runs official pinned PostgreSQL, ZITADEL API, Login V2 and Traefik images. Postgres/API/Login need `healthy`, proxy needs `running`.
- A synthetic marker row in disposable Postgres default `postgres` DB is written then validated after a database container restart and Compose health recovery.
- Existing `tests/ci/oidc_discovery.py` runs in a throwaway `python:3.12-alpine` container on the owned internal network, validates negative issuer/JWKS fixtures, real `/debug/ready`, exact OIDC issuer/metadata and a nonempty public JWKS.
- `tests/ci/backend_cleanup.sh` is run by an **always** step: it must find an ownership marker before any Docker teardown; only its Compose project is removed with `down -v`. Cleanup then checks that no owned containers, volumes or the fixed network remain. A missing marker means Docker was never started by this run and cleanup is not required; **not** a backend PASS.
This phase can verify local disposable backend runtime only. It **cannot** certify real account login, Admin Console session, MFA, global SSO logout, production TLS/Coolify or open Moderate package vulnerabilities. See `docs/P05-CI-03.md` for actual run evidence and `notes/P05-CI-03.md` for approval/scope.
+14
View File
@@ -121,3 +121,17 @@ For any approved update:
3. Change only approved files. Update relevant function/feature and user docs in the same phase.
4. Add change record to `project/CHANGELOG.md` and sync `MINIFEST.md` / source inventory if structure changes.
5. Do not rewrite or claim knowledge of every upstream function without examining it. Imported source internals stay officially sourced until audited for an approved edit.
## P05-CI-03 backend-only CI map
| Path | Actual role / ownership |
| --- | --- |
| `.gitea/workflows/p05-backend-acceptance.yml` | New manual backend-only Gitea job; excludes redundant Account/Login suites; bounded Alpine Git/Docker prerequisite, acceptance and always cleanup |
| `tests/ci/backend_acceptance.sh` | CI project collision checks, portless effective Compose, four services, disposable PostgreSQL restart, OIDC/JWKS smoke; **CI only** |
| `tests/ci/backend_cleanup.sh` | Cleanup gated on CI-generated ownership marker; down -v for that Compose project and orphan/volume/network checks |
| `tests/ci/compose.portless.override.yaml` | Existing P05-CI-02 CI-only reset of inherited P02 Traefik host binding; read-only in this phase |
| `tests/ci/oidc_discovery.py` | Existing negative and live metadata/JWKS verification; read-only in this phase |
| `docs/P05-CI-03.md`, `notes/P05-CI-03.md` | Public-facing CI procedure and accurate implementation/run evidence |
P02 dev Compose, core backend helper, Login V2 source, Account Portal and all dependency manifests remain unmodified.
+12
View File
@@ -90,3 +90,15 @@ Record: exact path, function name/signature, callers, inputs/outputs, error beha
| `main()` | Same | Check ZITADEL readiness, issuer discovery metadata and JWKS shape; print explicit interactive OIDC E2E BLOCKED |
Workflow service orchestration is in `.gitea/workflows/p05-ci.yml`, not Python. It executes only in Gitea CI; no local tests were requested. A green source check does not certify real authentication.
## P05-CI-03 backend CI shell entrypoints
| Symbol / entrypoint | Source | Exact behavior |
| --- | --- | --- |
| `dc()` in acceptance script | `tests/ci/backend_acceptance.sh` | Applies project-specific `docker compose` with the P02 dev file **plus** CI portless override on every operation |
| `backend_acceptance.sh` main | Same | Refuses existing project/network/volumes, runs prior backend helper static tests only in Gitea, creates disposable `.env`/ownership marker, checks effective Compose has no published ports, four-service state, Postgres restart marker, OIDC ready/discovery/JWKS |
| `dc()` in cleanup script | `tests/ci/backend_cleanup.sh` | Uses identical exact Compose project and two-file configuration only after an ownership marker is present |
| `backend_cleanup.sh` main | Same | Always-step removes only marked CI project with volumes; verifies no fixed network, matching project containers or volumes persist; no marker => no project teardown |
The scripts execute in the **Gitea Actions** runner, not on the local developer PC. Real user authentication and MFA are not implemented as CI checks.
+27 -20
View File
@@ -1,25 +1,27 @@
# Source inventory ? all Git-tracked paths
**Snapshot:** 2026-11-22, P05-CI-02 post-Run #83 documentation and CI-only portless correction based on tested `c27fe3d`. This source change has not been retested.
**Snapshot:** 2026-11-22, P05-CI-03 backend-only source preparation based on `4857558`. No claim of runtime PASS until the focused Gitea run completes.
**Tracked paths: 719.** Exact Git-index path list; untracked `AI_INSTRUCTIONS.md` and ignored secrets excluded. Source existence does not prove runtime acceptance.
**Git-tracked files: 724.** Untracked `AI_INSTRUCTIONS.md` and ignored secrets excluded.
| Top-level group | Files | Ownership |
This exact path inventory does not assert every upstream function was inspected. Consult `project/FILE-MAP.md` for first-party roles and `docs/P05-CI-03.md` for acceptance.
| Group | Files | Owner/purpose |
| --- | ---: | --- |
| `(repository root)` | 6 | Repository root |
| `.gitea` | 5 | Gitea manual CI workflows |
| `auth` | 639 | Upstream Login V2 import |
| `core` | 2 | Backend config/helper |
| `deployment` | 2 | Dev-only Docker Compose |
| `docs` | 14 | User/operator docs |
| `notes` | 6 | Phase scope and evidence |
| `packages` | 1 | Shared packages placeholder |
| `project` | 10 | Developer source map |
| `scripts` | 1 | Scripts placeholder |
| `tests` | 9 | CI verification scripts |
| `users` | 24 | Account Portal |
| `(repository root)` | 6 | Root files |
| `.gitea` | 6 | Gitea manual CI workflow files |
| `auth` | 639 | Official pinned Login V2 source |
| `core` | 2 | P02 dev orchestration |
| `deployment` | 2 | P02 local Compose |
| `docs` | 15 | User/operator guides and phase evidence |
| `notes` | 7 | Pre-change plans and phase reports |
| `packages` | 1 | First-party package placeholder |
| `project` | 10 | Developer file/function/CI mapping |
| `scripts` | 1 | Script placeholder |
| `tests` | 11 | CI/backend focused contracts |
| `users` | 24 | First-party Account Portal |
## Exact tracked paths
## Exact Git-tracked paths
### (repository root) ? 6 files
@@ -30,12 +32,13 @@
- `MINIFEST.md`
- `README.md`
### .gitea ? 5 files
### .gitea ? 6 files
- `.gitea/MINIFEST.md`
- `.gitea/README.md`
- `.gitea/workflows/MINIFEST.md`
- `.gitea/workflows/README.md`
- `.gitea/workflows/p05-backend-acceptance.yml`
- `.gitea/workflows/p05-ci.yml`
### auth ? 639 files
@@ -690,7 +693,7 @@
- `deployment/README.md`
- `deployment/docker/compose.backend.dev.yaml`
### docs ? 14 files
### docs ? 15 files
- `docs/ARCHITECTURE.md`
- `docs/DEVELOPMENT.md`
@@ -701,19 +704,21 @@
- `docs/P04-ACCOUNT-PORTAL.md`
- `docs/P05-CI-01.md`
- `docs/P05-CI-02.md`
- `docs/P05-CI-03.md`
- `docs/PHASES.md`
- `docs/README.md`
- `docs/SETUP-GUIDE.md`
- `docs/TROUBLESHOOTING.md`
- `docs/USER-GUIDE.md`
### notes ? 6 files
### notes ? 7 files
- `notes/CHANGELOG.md`
- `notes/DOCS-01.md`
- `notes/MINIFEST.md`
- `notes/P05-CI-01.md`
- `notes/P05-CI-02.md`
- `notes/P05-CI-03.md`
- `notes/README.md`
### packages ? 1 files
@@ -737,13 +742,15 @@
- `scripts/README.md`
### tests ? 9 files
### tests ? 11 files
- `tests/README.md`
- `tests/ci/MINIFEST.md`
- `tests/ci/README.md`
- `tests/ci/account_negative.py`
- `tests/ci/advisory_triage.py`
- `tests/ci/backend_acceptance.sh`
- `tests/ci/backend_cleanup.sh`
- `tests/ci/compose.portless.override.yaml`
- `tests/ci/oidc_discovery.py`
- `tests/ci/source_contract.py`