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:

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.
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.

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, 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

Confirm the consumer and repository in config/platform-infra/pipelines-as-code.yaml.
Run platform-infra pipelines-as-code history --target JD01 --consumer <id> --limit 10.
If the latest row is ambiguous, run history --id <pipelinerun> and inspect task counts, longest task, and env reuse source.
Run platform-infra pipelines-as-code status --target JD01 --consumer <id> for current runtime/GitOps alignment.
If status and history disagree, fix the status/history query first; do not infer env reuse behavior from an empty table.
For AgentRun, inspect image status, env identity, digest, and artifact catalog provenance.
For sentinel, inspect dependency reuse and BuildKit cache separately.

9.5 KiB Raw Blame History