mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document ci env reuse mechanics

Browse Source
This commit is contained in:
Codex
2026-07-06 02:21:12 +00:00
parent 5c8c7adbd2
commit 1bb58ec2d2
3 changed files with 96 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/unidesk-cicd/SKILL.md
+2
View File
@@ -30,6 +30,7 @@ bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel
- PR monitor 与自动合并: [references/pr-monitor.md](references/pr-monitor.md)。
- Tekton/Argo、node-scoped runtime lane、D601 infra bootstrap: [references/control-plane.md](references/control-plane.md)。
- HWLAB/AgentRun git-mirror source authority 与 flush: [references/git-mirror.md](references/git-mirror.md)。
- AgentRun/HWLAB env reuse 机制、证据解释和 PaC status/history 观察口径: [references/env-reuse.md](references/env-reuse.md)。
- Secret、observability、platform-infra、CI tools image、PipelineRun 清理和 rollout 补记: [references/platform-ops.md](references/platform-ops.md)。
- AgentRun YAML-only lane、v0.1 兼容入口和 AgentRun git-mirror: [references/agentrun.md](references/agentrun.md)。
- YAML-first K8s branch-follower 自动跟随、状态查询和 no-host-worktree 边界: [references/branch-follower.md](references/branch-follower.md)。
@@ -66,6 +67,7 @@ bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel
- PR 自动合并、v0.2/v0.3 lane 差异：读 [references/pr-monitor.md](references/pr-monitor.md)。
- 手动触发、定点 PipelineRun/source commit、RBAC/Pipeline/Argo、node-scoped runtime lane：读 [references/control-plane.md](references/control-plane.md)。
- git-mirror source authority 或 flush：读 [references/git-mirror.md](references/git-mirror.md)。
- AgentRun/HWLAB env reuse、`IMAGE_STATUS=reused`、`ENV_REUSE=hit`、`skipped,skip=<n>` 或 PaC history/status 解释：读 [references/env-reuse.md](references/env-reuse.md)。
- Secret、observability、CI tools image、PipelineRun/PV 清理：读 [references/platform-ops.md](references/platform-ops.md)。
- AgentRun v0.1 或 YAML-only lane 部署：读 [references/agentrun.md](references/agentrun.md)。
- 三运行面 branch follower 自动跟随、`apply/status/run-once/events/logs`：读 [references/branch-follower.md](references/branch-follower.md)。
.agents/skills/unidesk-cicd/references/agentrun.md
+1 -1
View File
@@ -40,7 +40,7 @@ PaC closeout 的首选状态入口是：
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01
```
默认状态必须显示 controller/CRD/webhook ready、最新 PipelineRun 和 TaskRun duration、`IMAGE_STATUS`、env identity、image digest、GitOps commit、Argo revision/health 和 runtime source/env annotations。env reuse 的接受证据是 `IMAGE_STATUS=reused`、同一 env identity 和稳定 digest；首次 cache miss 构建可以超过 120s，但最终收口应以后续 env-reuse 的秒级 PipelineRun 为准。
默认状态必须显示 controller/CRD/webhook ready、最新 PipelineRun 和 TaskRun duration、`IMAGE_STATUS`、env identity、image digest、GitOps commit、Argo revision/health 和 runtime source/env annotations。env reuse 机制和证据解释统一见 [env-reuse.md](env-reuse.md)，本文件不重复维护第二套口径。
JD01 v0.2 的 runtime boot repoURL、Argo repoURL 和 CI git read URL 必须使用 Gitea internal read URL。若仍指向 legacy git-mirror read URL，runtime 可能因 `git-mirror-exact-commit-unavailable` 崩溃，因为对应 commit 只存在于 Gitea snapshot/source。GitOps publish 必须用 PaC/Gitea token Secret 写回 Gitea mirror；如果 `platform-infra pipelines-as-code status` 中 GitOps commit 已推进但 Argo revision 未追上，可以用 `bun scripts/cli.ts agentrun control-plane refresh --node JD01 --lane jd01-v02 --confirm` 触发受控 hard refresh，但持久修复是 Gitea write path 和 Argo repoURL 对齐，不是 legacy git-mirror flush。
.agents/skills/unidesk-cicd/references/env-reuse.md
+93
View File
@@ -0,0 +1,93 @@
# Env Reuse
Env reuse is the CI/CD optimization that decides whether a pipeline can reuse an already prepared environment artifact or dependency set instead of rebuilding the same environment from scratch. It is not a single implementation. In UniDesk today it has two concrete shapes:
- AgentRun manager image reuse: compare source-declared identity files, reuse an existing image artifact when the environment identity is unchanged, and skip the image build stage.
- Web sentinel dependency reuse: link a node-local dependency directory into the build workspace and rely on BuildKit state for image build acceleration.
Do not collapse these into one meaning. A status value of `reused`, `hit`, `skipped`, or `cache=hit` must be interpreted in the context of the consumer that produced it.
## Source Of Truth
The reusable CI/CD contract is declared in `gitops/reuse.ymal` inside the source repository snapshot consumed by CI. UniDesk parses it through `scripts/src/cicd-reuse-config.ts`; helper script parity exists in `scripts/native/cicd/reuse-config-summary.mjs` and branch-follower gate code.
The relevant service fields are:
- `runtimeReuse`: source/runtime identity comparison. It can declare `codeIdentity.paths` and `envIdentity.paths`.
- `envReuse`: environment identity and dependency reuse declaration. It can declare `enabled`, `mode`, `nodeDepsPath`, `envIdentityFiles`, and `buildArgs`.
All paths in `gitops/reuse.ymal` are relative to the source tree, except runtime dependency locations such as a node-local `nodeDepsPath` where the owning runtime YAML explicitly declares the path. Do not invent default path lists in code or docs. If a service requires env reuse, use `requiredReuseServiceError(..., "envReuse")` style validation so missing declarations are reported before a pipeline silently falls back.
## AgentRun
AgentRun manager env reuse is identity based. `scripts/src/cicd-agentrun-reuse.ts` reads the `agentrun-mgr` or `manager` service from `gitops/reuse.ymal` and computes a reuse decision against the current snapshot and its parent commit:
- `sourceIdentity` hashes configured code identity paths.
- `envIdentity` hashes configured env identity paths plus `envReuse.envIdentityFiles`.
- `runtimeReuse` hits only when both source and env identity hit.
- `envReuse` hits when env identity hits.
- Either hit can set `skipImageBuild=true`.
When the build is skipped, AgentRun consumes the existing artifact catalog entry from the GitOps branch instead of creating a new image. The artifact must still provide image, digest, and env identity for `agentrun-mgr`; otherwise reuse is invalid and the pipeline must build or fail visibly. Passing evidence is `IMAGE_STATUS=reused`, a stable `ENV_ID`, a digest, and a GitOps commit from `platform-infra pipelines-as-code status|history`.
AgentRun Tekton also has an in-pipeline image probe path in `scripts/src/agentrun-manifests.ts`: checkout computes an env identity from configured files, probes the local registry for an image tagged by that identity, writes `status=reused` and `skip-build` on hit, otherwise runs BuildKit and writes `status=built`.
## Web Sentinel
Web sentinel env reuse is dependency reuse, not whole-image reuse. `scripts/src/hwlab-node-web-sentinel-cicd.ts` overlays `gitops/reuse.ymal` service ids `web-probe-sentinel` or `monitor-web` onto the sentinel `monitorWeb.envReuse` config. The actual publish job in `scripts/src/hwlab-node-web-sentinel-cicd-jobs.ts`:
- checks whether the YAML-selected `nodeDepsPath` exists on the target node/build workspace;
- removes workspace `node_modules`;
- symlinks packages from the reusable dependency directory into workspace `node_modules`;
- emits `sentinel-publish-env-reuse` with `dependencyReuse=hit|miss`, entry counts, and linked count;
- then verifies the monitor web assets and builds the image through the configured BuildKit path.
For sentinel, `ENV_REUSE=hit` means the dependency directory was present and linked. It does not mean the image build was skipped. The image may still be published in the same run; separate BuildKit evidence such as `cache=hit` describes layer/cache behavior.
## Gitea PaC Observation
Gitea/Pipelines-as-Code is the current operator-facing observation surface for migrated JD01 consumers. The canonical commands are:
```bash
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01 [--consumer <id>]
bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 [--consumer <id>] [--limit 10]
bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --id <pipelinerun>
```
`status` reports latest PipelineRun, TaskRun durations, image status, env identity, digest, GitOps revision, Argo health, and runtime image. `history` reads live Gitea Repository CR plus Tekton PipelineRun/TaskRun objects on the target node, aggregates there, and returns Beijing-time display according to `config/platform-infra/pipelines-as-code.yaml`.
The history/status env reuse display is log-derived:
- JSON records with `envReuse`, `envReuseStatus`, `buildSkippedCount`, `serviceReusedCount`, or equivalent fields are parsed.
- Sentinel's compact table headed `ENV_REUSE NODE_DEPS ...` is parsed as human-readable fallback.
- Missing env reuse text is not proof that no reuse happened; first check the consumer type, the relevant TaskRun logs, and whether the pipeline emits the expected fields.
## Interpreting Results
Use these interpretations:
- AgentRun `IMAGE_STATUS=reused`: image build was skipped or registry artifact reused for the same env identity.
- AgentRun `IMAGE_STATUS=built`: env identity did not hit or registry/artifact probe missed; a new image was built.
- Sentinel `ENV_REUSE=hit`: node dependency directory was present and linked before verify/build.
- Sentinel `cache=hit`: BuildKit cache evidence, separate from dependency reuse.
- HWLAB v0.3 `skipped,skip=<n>` 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.
Do not use one consumer's evidence vocabulary to judge another consumer. In particular, do not expect every PaC consumer to expose an `ENV_ID`, and do not treat a blank `ENV_REUSE` cell as a failed env reuse without checking the consumer implementation.
## Common Pitfalls
- `status` and `history` must use the same PipelineRun matching contract: name prefix or Tekton pipeline label. Requiring a PaC repository label can hide valid HWLAB PipelineRuns because not every generated PipelineRun carries that label.
- 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.
## Debug Checklist
1. Confirm the consumer and repository in `config/platform-infra/pipelines-as-code.yaml`.
2. Run `platform-infra pipelines-as-code history --target JD01 --consumer <id> --limit 10`.
3. If the latest row is ambiguous, run `history --id <pipelinerun>` and inspect task counts, longest task, and env reuse source.
4. Run `platform-infra pipelines-as-code status --target JD01 --consumer <id>` for current runtime/GitOps alignment.
5. If status and history disagree, fix the status/history query first; do not infer env reuse behavior from an empty table.
6. For AgentRun, inspect image status, env identity, digest, and artifact catalog provenance.
7. For sentinel, inspect dependency reuse and BuildKit cache separately.