From 52665fcce858d1fab7bf77ff92898c53ce94539d Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 20 May 2026 00:47:15 +0000 Subject: [PATCH] docs: add cicd precheck evidence matrix --- docs/reference/cicd-standardization.md | 44 ++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/reference/cicd-standardization.md b/docs/reference/cicd-standardization.md index 08c26f27..78a1dbec 100644 --- a/docs/reference/cicd-standardization.md +++ b/docs/reference/cicd-standardization.md @@ -25,6 +25,34 @@ The standard release shape is: The current precheck could inspect the locally cached image labels and image id, but Docker Hub and registry HTTP requests timed out from this container. Therefore the catalog records `digestPin.status=pending-network-verification`; rollout must remain blocked until a reachable registry path resolves the manifest digest and records the mirror digest. The locally cached image shows `org.opencontainers.image.version=2.63.3`, `org.opencontainers.image.revision=ca5e249e3c0c94159c2136a0cd431a424eb18472`, `linux/amd64`, and image id `sha256:6a4d051140ef9313ad87b443f55ccb1cd6331e7463b4becbec2174b494ea533c`, but a local image id is not a registry digest pin. +### Upstream Image Evidence + +The catalog expression is intentionally minimal and parseable: + +| Evidence command | Required result shape | +| --- | --- | +| `jq '.upstreamImageConsumers[] | {serviceId, upstreamImageRef, digestPin, mirrorStrategy, ciBuild, pullOnlyCdValidation}' CI.json` | both File Browser services show `upstreamImageRef=docker.io/filebrowser/filebrowser:v2.63.3`, `digestPin.required=true`, `digestPin.status=pending-network-verification`, `mirrorStrategy.mode=mirror-after-digest-verification`, `ciBuild.dockerfileBuild=false`, and `publishCommand=null` | +| `bun scripts/cli.ts config show` with the File Browser `artifactSource` projection | both services parse as `kind=upstream-image`, `digestPinRequired=true`, `mirrorRepository=127.0.0.1:5000/upstream/filebrowser/filebrowser`, `ciDockerfileBuild=false`, and `pullOnlyCd=true` | +| `docker image inspect filebrowser/filebrowser:v2.63.3` | local cache evidence may show the image id and OCI labels for version `2.63.3` and revision `ca5e249e3c0c94159c2136a0cd431a424eb18472`; this is not a registry digest | +| `docker manifest inspect --verbose docker.io/filebrowser/filebrowser:v2.63.3` | must resolve an upstream manifest digest before rollout; when the registry request times out, rollout remains blocked and the catalog stays at `pending-network-verification` | +| `bun scripts/cli.ts ci publish-user-service --service filebrowser --commit --dry-run` | returns `ok=false` with the message that File Browser is an upstream image consumer and must not be built by Dockerfile CI | + +The digest/mirror dry-run contract is: + +1. Resolve `docker.io/filebrowser/filebrowser:v2.63.3` to `docker.io/filebrowser/filebrowser@sha256:`. +2. Mirror only that resolved digest to `127.0.0.1:5000/upstream/filebrowser/filebrowser@sha256:`. +3. Record the digest ref used by CD; do not promote a mutable tag as release truth. +4. Refuse pull-only CD while the digest is unknown or the mirror digest differs from the upstream digest. + +Pull-only CD validation must be expressed as concrete checks: + +| Check | Form | +| --- | --- | +| Pull source | `docker pull docker.io/filebrowser/filebrowser@sha256:` or `docker pull 127.0.0.1:5000/upstream/filebrowser/filebrowser@sha256:` | +| Runtime identity | `docker inspect` reports the expected image id/digest and OCI labels `org.opencontainers.image.version=2.63.3` and `org.opencontainers.image.revision=ca5e249e3c0c94159c2136a0cd431a424eb18472` | +| Service health | UniDesk private proxy health succeeds for `filebrowser` and `filebrowser-d601`; direct public exposure remains forbidden | +| Build absence | no `docker build`, `docker compose up --build`, CI Dockerfile producer, or source checkout is used for these services | + ## Legacy Path Classification | Path | Classification | Current guardrail | Cleanup condition | @@ -47,6 +75,22 @@ The current precheck could inspect the locally cached image labels and image id, - Local-manifest production deploy for reviewed artifact consumers is blocked before source materialization/build, so prod cannot silently fall back to target-side source build or a dirty worktree. - `artifact-registry deploy-backend-core` is demoted to a structured deprecated result; backend-core production CD must enter through `deploy apply --env prod`. +### Guardrail Evidence Matrix + +| Guardrail name / result key | Command evidence | Legacy path covered | Deletion status | +| --- | --- | --- | --- | +| `upstream-image` CI publish rejection | `bun scripts/cli.ts ci publish-user-service --service filebrowser --commit --dry-run` returns `ok=false` and says not to build an upstream image consumer | File Browser accidentally entering `CI.json.artifacts[]` or Dockerfile CI | keep; deletion of docker-run repair waits for digest/mirror CD | +| `prod-artifact-consumer-local-manifest-blocked` | `bun scripts/cli.ts deploy apply --file deploy.json --service frontend --dry-run` returns `ok=false`, this error key, and points to `deploy apply --env prod --service --commit ` | prod source-build fallback for reviewed artifact consumers | keep; local manifest mode may still be needed for non-prod/recovery until runbooks are replaced | +| `artifact-registry deploy-backend-core` deprecated result | `bun scripts/cli.ts artifact-registry deploy-backend-core --commit ` returns `ok=false`, `deprecated=true`, and replacement `deploy apply --env prod --service backend-core --commit ` | backend-core prod CD bypassing deploy reconciler guardrails | keep name only as compatibility until all callers stop using it | +| prod unsupported result for services without artifact consumers | `deploy apply --env prod --service --dry-run` must return unsupported instead of falling back to source build | target-side source build/maintenance-channel prod deploy | keep disabled until service-specific artifact consumers exist | +| backend-core/code-queue prod boundary | docs and deploy support matrix allow backend-core and D601 Code Queue only in dev validation for this phase | accidental prod validation entrypoints for backend-core or Code Queue | do not add executable prod test/deploy validation in this precheck | + +The guarded-but-not-deletable paths are: `server rebuild backend-core`, `server rebuild frontend`, `server rebuild baidu-netdisk`, provider-gateway protected upgrade, native k3s bootstrap, k3sctl-adapter bridge repair, File Browser provider-local docker-run repair, and D601 dev/backend target-side rollout. They remain because they are bootstrap, recovery, diagnostic, or controlled dev paths; deleting them requires replacement runbooks or reviewed artifact consumers. + ## Not Removed Yet Bootstrap and repair paths remain because they still protect recovery: native k3s initialization, provider-gateway protected upgrade, k3sctl-adapter control bridge repair, main-server Compose maintenance rebuilds, and File Browser docker-run operations. These paths must be replaced by reviewed artifact consumers or explicit recovery runbooks before deletion. + +## Validation Boundary + +This precheck uses lightweight parsing and dry-run evidence only. It intentionally does not run full `check`, e2e, Playwright, or other broad browser/runtime test suites on the master server because those are outside the precheck scope and may exceed master-server resource limits. `backend-core` and D601 `code-queue` production validation are also out of scope; backend-core dev rollout can be attempted only through the existing D601 dev path, and a provider-offline result is an infrastructure blocker rather than permission to validate production.