diff --git a/.agents/skills/unidesk-cicd/references/control-plane.md b/.agents/skills/unidesk-cicd/references/control-plane.md index caa2ee50..8807ec7b 100644 --- a/.agents/skills/unidesk-cicd/references/control-plane.md +++ b/.agents/skills/unidesk-cicd/references/control-plane.md @@ -44,6 +44,10 @@ bun scripts/cli.ts hwlab nodes control-plane refresh --node --lane v03 -- 120 秒是同一条 CLI 的端到端预算，不是每个子阶段各等一轮。嵌套 git-mirror sync/flush 必须按剩余预算裁剪并跳过多次 retry；状态探测也必须按剩余预算收窄。超预算时 CLI 返回 `pending` warning，输出阶段分解、PipelineRun 状态、GitOps flush revision、Argo observed/target revision、runtime/public readiness、pending TaskRun/Pod drill-down 和下一条受控 status 命令。PipelineRun 已成功但 Argo/runtime/public 仍在收敛时，状态原因应落在 Argo/runtime closeout，不再泛化成 CI TaskRun pending。 +CI/CD closeout 的 public gate 只验证选中 node/lane 的 formal public HTTPS `/health` 入口和必要 provenance。`web-probe`、Playwright、远程浏览器、DOM quick-verify 和用户路径 E2E 只能作为发布后的独立业务验证证据，不能作为 CI/CD gate、timeout blocker 或 closeout 必要条件。public gate 失败时先对齐 YAML publicExposure、GitOps 渲染出的 `frpc` ConfigMap/Deployment、Secret key presence、frpc 日志、PK01/Caddy loopback 和目标侧 HTTPS probe；不要把裸 FRP 端口、legacy 端口或 web-probe 超时当作 CI/CD 结论。 + +FRP/Caddy 类 closeout 要同时看 ConfigMap 与 Pod 实际加载状态。ConfigMap 或 Secret 对象存在不等于 frpc 已登录成功；必须检查运行中 Pod 日志是否有目标 proxy `start proxy success`，并区分 `port already used`、`port not allowed`、`token in login doesn't match token from configuration` 和 upstream service 502。frpc token 必须通过 YAML sourceRef 下发为 Kubernetes Secret，再由源码渲染以 SecretRef/env/template 消费；不要把 token 明文写入 GitOps ConfigMap、issue、日志或 reference。 + `sync --confirm` 是 Argo runtime 收敛修复入口：先按 YAML 同步本地 postgres bootstrap Secret，再终止卡住的 running Argo operation、删除失败 hook Job，并在 StatefulSet template 已更新但旧 controller-revision pod 因 `ImagePullBackOff` / `ErrImagePull` / `CrashLoopBackOff` 卡住时受控删除该旧 pod。不要手工裸删 pod。 ## D601 Infra Bootstrap diff --git a/.agents/skills/unidesk-cicd/references/env-reuse.md b/.agents/skills/unidesk-cicd/references/env-reuse.md index b2df8b12..b60a61f6 100644 --- a/.agents/skills/unidesk-cicd/references/env-reuse.md +++ b/.agents/skills/unidesk-cicd/references/env-reuse.md @@ -72,6 +72,7 @@ Use these interpretations: - Sentinel `cache=hit`: BuildKit cache evidence, separate from dependency reuse. - HWLAB v0.3 `skipped,skip=` in PaC history: service-level artifact planning skipped builds for already reusable services; inspect the detail id before interpreting it as AgentRun-style image reuse. - HWLAB v0.3 `env-reuse-git-mirror-checkout`: a `codeIdentity` change with unchanged `envIdentity` should mark the service as affected/rolled out while still skipping image build. Evidence is in `plan-artifacts` and `collect-artifacts`: `affectedServices` includes the service, `buildServices=[]`, the artifact has `ciAffected=true`, `ciReason` such as `code-input-changed`, a new `componentCommitId`/`codeInputHash`, and `publishState=reused` / `buildBackend=reused-env-catalog`. This is correct env reuse consumption, not a missed rebuild. +- HWLAB v0.3 shared TS runtime env groups build one representative environment image and let compatible TS services consume that same artifact with different runtime checkout/entrypoint metadata. A semantic env identity change, such as dependency maps, `engines`, `packageManager`, `overrides`, `resolutions`, `type`, or env launcher inputs, should schedule the representative build service; consumer services should keep shared artifact provenance and skip individual image builds. - HWLAB v0.3 non-reuse image build is expected when `envIdentity` changes, such as shared dependency or env launcher inputs. Then `buildServices` should include services whose environment identity changed and build TaskRuns should be present. - HWLAB v0.3 treats `package.json` env identity semantically. Arbitrary top-level metadata fields do not count; meaningful env inputs include dependency maps, `overrides`, `resolutions`, `engines`, `packageManager`, and `type`. Use one of those fields when deliberately testing non-reuse behavior. @@ -83,7 +84,7 @@ Do not use one consumer's evidence vocabulary to judge another consumer. In part - PaC history has no UniDesk-owned history database. If a row is missing, inspect live target-side reads and read errors before concluding the pipeline never ran. - Env reuse is a CI/build concern. The k8s runtime boundary still starts when Kubernetes pulls the already built or reused image; runtime must remain Docker-free. - Do not preserve a second trigger path to "test" env reuse. Use the configured source authority and trigger path for that consumer, then observe through `status`/`history`. -- Do not add contract tests or hard-code business thresholds for reuse. Validate shape, required declarations, target-side PipelineRun evidence, artifact digest, GitOps revision, Argo health, and runtime provenance. +- Do not add contract tests or hard-code business thresholds for reuse. Validate shape, required declarations, target-side PipelineRun evidence, artifact digest, GitOps revision, Argo health, runtime provenance, and the formal public HTTPS `/health` probe when the consumer has a public runtime. Do not use web-probe/Playwright as env reuse or CI/CD closeout evidence. ## Debug Checklist diff --git a/docs/reference/cicd-standardization.md b/docs/reference/cicd-standardization.md index 0087d8b8..b5da30ea 100644 --- a/docs/reference/cicd-standardization.md +++ b/docs/reference/cicd-standardization.md @@ -26,6 +26,8 @@ Network identity is part of the evidence. `127.0.0.1:5000` may mean runner-pod l Manual hotfixes are allowed only to recover and learn the missing contract. The durable close-out is a repo-owned preflight, desired-state check, CLI behavior, or reference update, followed by the same verification from the actual runner environment. A healthy old live service does not prove CD success; success requires the formal job to pass and live commit or digest identity to match the desired state. +For node-scoped HWLAB/Gitea/PaC lanes, CI/CD closeout stops at PipelineRun success, GitOps/Argo sync and health, runtime readiness/provenance, git-mirror alignment, and the formal public HTTPS `/health` probe declared by YAML. Browser automation, `web-probe`, Playwright, DOM assertions and user-path E2E are post-deploy product validation, not CI/CD gates. FRP/Caddy public exposure failures are diagnosed by aligning YAML publicExposure, GitOps-rendered frpc config, Secret key presence, frpc login/proxy logs, PK01/Caddy loopback and target-side HTTPS probe; Secret values are never recorded in docs or issue comments. + ## Target Shape The standard release shape is: