pikasTech-unidesk/.agents/skills/unidesk-cicd/SKILL.md

name, description

name

description

unidesk-cicd

UniDesk CI/CD 控制面 — `cicd branch-follower`、`hwlab g14`、`hwlab nodes control-plane` 和 `agentrun` 子命令，覆盖自动跟随 branch、PR 监控自动合并、Tekton/Argo 控制面、git-mirror、Secret、observability、CI tools image、PipelineRun 清理、AgentRun v0.1 部署和 AgentRun YAML-only lane 部署。用户提到 CI/CD、deploy、rollout、PipelineRun、trigger、git-mirror、control-plane、k8s/k3s 部署、branch follower、自动跟随、agentrun 部署、hwlab g14、monitor-prs、trigger-current 时使用。任何需要把代码变更推送部署到 G14 k3s 的操作都必须走本 skill。

UniDesk CI/CD

HWLAB G14 和 AgentRun CI/CD 的受控入口。任何 PR 监控、Tekton/Argo、git-mirror、Secret、observability、CI tools image、PipelineRun 清理或 AgentRun 部署都必须走 bun scripts/cli.ts。

高频入口

bun scripts/cli.ts cicd status --node NC01
bun scripts/cli.ts cicd status --node <NODE>
bun scripts/cli.ts hwlab g14 monitor-prs --lane v02 --once --dry-run
bun scripts/cli.ts hwlab g14 control-plane status --lane v02
bun scripts/cli.ts hwlab nodes control-plane status --node NC01 --lane v03 --json
bun scripts/cli.ts hwlab g14 control-plane trigger-current --lane v02 --confirm --wait
bun scripts/cli.ts hwlab g14 git-mirror status --lane v02
bun scripts/cli.ts agentrun control-plane status
bun scripts/cli.ts platform-infra gitea mirror status --target JD01
bun scripts/cli.ts platform-infra gitea mirror webhook status --target JD01
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01 --consumer hwlab-jd01-v03
bun scripts/cli.ts platform-infra pipelines-as-code closeout --target JD01 --consumer <consumer> --source-commit <sha> --wait
bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --limit 10
bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --id <pipelinerun>
bun scripts/cli.ts platform-infra pipelines-as-code debug-step --target JD01 --consumer <consumer>
bun scripts/cli.ts platform-infra pipelines-as-code debug-step --target JD01 --consumer <consumer> --id <pipelinerun>
bun scripts/cli.ts platform-infra pipelines-as-code source-artifact check --target NC01 --consumer <consumer> --source-worktree <absolute-path>
bun scripts/cli.ts platform-infra pipelines-as-code source-artifact write --target NC01 --consumer <consumer> --source-worktree <absolute-path> --confirm
bun scripts/cli.ts platform-infra pipelines-as-code source-artifact verify-runtime --target NC01 --consumer <consumer> --source-worktree <absolute-path> --source-commit <full-sha>

节点级只读状态必须优先用 cicd status --node <NODE>。它从 config/platform-infra/pipelines-as-code.yaml 找到该 node 的所有当前 PaC consumer，一次性汇总 PipelineRun、Argo/GitOps、runtime readiness 和诊断；不要再靠阅读源码或手动拼三条 consumer 命令来回答 “NC01 的 CI/CD 流水线情况”。platform-infra pipelines-as-code status --target <NODE> --consumer <id> 只作为单 consumer drill-down。

按职责读取拆分后的 reference：

• PR monitor 与自动合并: references/pr-monitor.md。
• Tekton/Argo、node-scoped runtime lane、D601 infra bootstrap: references/control-plane.md。
• HWLAB/AgentRun git-mirror source authority 与 flush: references/git-mirror.md。
• JD01/NC01 Gitea mirror + Pipelines-as-Code 正式架构、三 consumer 覆盖矩阵、target 级 webhook path 和旧入口处置: references/gitea-pac.md。
• AgentRun/HWLAB env reuse 机制、证据解释和 PaC status/history 观察口径: references/env-reuse.md。
• Secret、observability、platform-infra、CI tools image、PipelineRun 清理和 rollout 补记: references/platform-ops.md。
• AgentRun YAML-only lane、v0.1 兼容入口和 AgentRun git-mirror: references/agentrun.md。
• YAML-first K8s branch-follower 自动跟随、状态查询和 no-host-worktree 边界: references/branch-follower.md。

P0 边界

• CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 部署必须走受控 CLI；不要用裸 kubectl、argo、tkn、curl 当正式控制入口。
• CI/CD source authority 只能来自 YAML 声明的 Kubernetes 托管 source authority：legacy lane 使用 k8s git-mirror snapshot，Gitea/PaC migrated lane 使用 GitHub PR merge -> GitHub webhook bridge -> Gitea controlled mirror + immutable snapshot ref -> Pipelines-as-Code。受控命令先在 k8s 内同步/创建不可变 refs/unidesk/snapshots/.../<commit> stage ref；build/status/publish 只消费该 snapshot，host worktree、本地 git fetch/pull、可变 branch ref 或 Pipeline 内直连 GitHub 都不能作为 authoritative source。
• JD01/NC01 agentrun-<node>-v02、sentinel-<node>-v03、hwlab-<node>-v03 的正式 CI/CD closeout 入口是 cicd status --node <NODE> 和 platform-infra pipelines-as-code closeout|status|history --target <NODE> --consumer <id>。closeout 是通用 consumer 引导入口，只读取/等待 PaC、Tekton、GitOps、Argo 和 runtime 对齐，不触发旧手动发布。cicd branch-follower 和 cicd gitea-actions-poc 对这些 consumer 只保留历史/迁移只读用途，不得作为当前交付判断入口。
• PaC .tekton 文件必须用 Repository CR 的 target/node 参数隔离 JD01/NC01，避免同一个 Gitea push 在一个 target cluster 内额外创建另一个 target 的 PipelineRun；history/detail 必须按实际 PipelineRun prefix/pipeline 归属 consumer。
• PaC source artifact 必须遵循以下边界：
  • 由 config/platform-infra/pipelines-as-code.yaml#consumers[].sourceArtifact 显式声明；
  • 通过 source-artifact plan|check|write|status|verify-runtime 管理；
  • taskRunTemplate 等运行事实归属 owning YAML，代码只负责校验和渲染；
  • desired 只来自 owning YAML 与共享 renderer，禁止从 live Pipeline/PipelineRun 反向导出；
  • verify-runtime 使用干净且 HEAD 等于完整 source commit 的独立 worktree；
  • 未声明 owner、worktree 证据不成立或运行面证据冲突时 fail-closed；
  • 错误和 drift 在默认、--json、--full 中都只能披露路径、类型、长度、SHA-256 或 URL fingerprint；
  • 禁止回显脚本、URL 凭据、查询参数、Authorization、Secret 和远端 stderr。
• PaC source-only closeout 必须使用目标侧结构化证据：
  • g14-ci-plan 的 source commit、affected/build/rollout 计数必须完整；
  • collect-artifacts 与 gitops-promote 必须同时明确 no-build-no-rollout-plan；
  • 三者一致时才允许返回 no-runtime-change 和 retained provenance；
  • 仍要求 PipelineRun 成功、原 Argo Synced/Healthy、runtime ready、sha256 digest pin 与 health ready；
  • 证据缺失、冲突或 source commit 不匹配必须 fail-closed，不得等价为 delivery disabled，也不得伪造新 artifact、GitOps revision 或 runtime source commit。
• PaC status|closeout|history 的 --json 是有界 machine contract；--full 展开单条详情，--raw 才展开目标侧原始 payload。history --id --full 不得重复嵌套同一 rows/consumer payload或依赖 /tmp/unidesk-cli-output 才可读。
• PaC debug-step --id <pipelinerun> 必须读取目标侧真实 PipelineRun、TaskRun condition/result 与合同 Task 日志：
  • 默认输出每个 terminal role 的 presence、status、source 与首个断点；
  • 同时披露 artifact catalog、digest、GitOps commit 和 collector 读错；
  • 该入口只读且 mutation=false，不能创建 PipelineRun 或写 GitOps/runtime；
  • 未带 --id 时才只运行 evaluator fixture。
• GitHub/Git 相关 egress 必须走 YAML-first host proxy/sourceRef：branch-follower controller 读 config/cicd-branch-followers.yaml#controller.source.githubSsh，runtime legacy git-mirror 读 owning lane/control-plane YAML 的 host proxy 和 githubTransport，Gitea/PaC 迁移 lane 读 config/platform-infra/gitea.yaml 与 config/platform-infra/pipelines-as-code.yaml；禁止依赖未声明 host env、trans proxy、裸直连 GitHub 或 CLI 输出解析。
• Gitea/PaC lane 的 GitHub -> Gitea 自动同步必须用 platform-infra gitea mirror webhook apply|status|test。该路径是单向同步，只更新 Gitea branch 和 immutable snapshot ref；不得引入 Gitea -> GitHub 回写、轮询 fallback、Gitea Actions/act_runner fallback 或第二套状态存储。
• Gitea webhook/FRPC/Caddy 变更的 closeout 必须看受控 CLI 的 rollout/status/test 证据；Secret 或 ConfigMap apply 成功不等于 connector Pod 已加载新 proxy/path。
• cicd branch-follower 的自动跟随全过程不得读取或挂载 host worktree、target dev dir、.worktree/* 或 local git checkout；controller pod/一次性 reconcile Job 只能用 k8s git-mirror cache、Tekton PipelineRun、Argo Application、runtime workload 和 EmptyDir 执行，状态以 K8s ConfigMap/Lease 承载的 native observation 为准，不得解析下游 CLI 输出。
• k8s 运行面从拉取已构建镜像开始必须 0 Docker；CI 构建面可以使用 YAML 声明的原生构建工具，但不得把 Docker socket、Docker daemon 或 host Docker 带入运行面。
• 正式 CI/CD、publish、image build 和 rollout 必须走 Tekton Task/Pipeline/PipelineRun 承担 CI，并通过 GitOps/Argo 承担部署收敛；普通 Kubernetes Job 只允许用于 bounded helper、source sync、diagnostic、cleanup 或 bootstrap，不得作为正式发布、镜像构建或 rollout 入口。
• 正式 CI/CD 必须提供一键完成入口：同一受控命令应完成 source sync、构建、发布、GitOps/Argo 收敛、runtime provenance 校验和 /health 端点验证；不要要求操作者手动串联多个 publish/apply/status 命令才能完成一次交付。
• CI/CD 一键交付的端到端 wall-clock 目标是低于 2 分钟；计时从操作者触发受控命令开始，到 runtime ready 且 /health 端点验证完成为止。具体 wait/timeout/budget 字段必须从 YAML/source-of-truth 读取并配置到满足该目标。
• CI/CD validation 阶段只能验证部署对象的 /health 端点和必要 provenance；禁止在 CI/CD gate 中运行 web-probe、Playwright、远程浏览器截图、用户路径 E2E 或等价重型业务探针。业务/用户入口验证只能作为发布后的独立 post-deploy validation 证据，不得阻塞 CI/CD 一键交付。
• 任一 CI/CD 阶段或总耗时超过 2 分钟时，不要继续死等或把超长等待视为正常；先输出阶段耗时分解，并优先从 env reuse、git mirror、BuildKit/cache、GitOps/Argo watch 和 runtime readiness 探测方向优化后再继续交付。
• node-scoped trigger-current --wait 必须把 source sync、pre/post flush、PipelineRun、GitOps/Argo、runtime readiness 和 /health closeout 放进同一 120s 端到端预算；超预算时由 CLI 输出阶段分解、Argo target revision、runtime/public 状态和 TaskRun/Pod drill-down，不继续死等，也不要求操作者手动串联多个状态/flush 命令才能完成一次交付。
• node-scoped control-plane status 可见性规则：
  • 必须立即输出 started/阶段，并按 owning YAML 输出 heartbeat；
  • 正常、总预算超时、中断和 worker 失败都要返回有界 closeout；
  • closeout 必须披露探针完成情况、进程组清理结果和脱敏的 worker 错误摘要；
  • 显式 --json 的 stdout 只允许一个合法 JSON 文档，progress 写入 stderr。
• 触发或验收 rollout 时必须绑定 lane、source commit、PipelineRun/GitOps revision、runtime ready 和 /health 端点验证结果；web-probe/Playwright 结果只能作为单独的 post-deploy 证据。
• CI/CD 状态、日志和事件查询必须减少 trans/SSH 传输：能在目标 NODE/k8s 内解析、聚合、裁剪的内容，必须在目标侧计算成短 JSON/table 摘要后再回传；禁止为了本地解析而把完整 ConfigMap、大对象、长日志或原始 API payload 透传回来。
• branch-follower 排障必须优先使用 debug-step 做单步调试：state-read、status-read、decide、state-write 分别定位状态读取、K8s native status、决策和 ConfigMap patch，不要通过反复推小提交触发整条自动跟随大回环来定位同一问题。
• branch-follower 的“单步”不是端到端流水线里的被动观察点；reuse plan、CI 并行/TaskRun plan、CD rollout plan、post-deploy health/monitoring 每个 gate 都必须有可独立触发、独立执行、独立复测的目标侧 CLI/debug-step/drill-down 入口。没有这个入口时先补入口，再做 run-once、自动 loop 或小 PR 联调。
• branch-follower 单步测不通时应继续在该单步边界内定位和修复，直到目标侧复测通过；不要把普通 gate 失败包装成阻塞结论。只有权限缺失、外部依赖不可达、架构取舍或明确超出当前授权范围时，才写 issue 阻塞和下一步最小范围。
• CI/CD 排障中再次踩到已经暴露过的运行面坑、工具误用、镜像假设或状态可见性缺口时，必须先把长期规则写入本 skill/reference，再继续单步调试；branch-follower 必须先让相关 debug-step 单步全部通过，再做 run-once、自动 loop 或小 PR/小提交联调。
• CI/CD 验证、测试和性能度量必须在目标 NODE/k8s 内执行，尤其是 branch-follower、Tekton/Argo、runtime reuse/env reuse、git mirror 和 runtime-ready 相关改动；不要在 master/local host 跑 test 或用本地验证结果替代目标运行面证据。本机只用于源码阅读、编辑和必要静态语法检查，正式收敛结论必须来自目标 NODE 计算出的短摘要。
• in-cluster/controller/native helper 不能假设镜像内存在 kubectl binary。目标 Pod/Job 内读取或写入 Kubernetes 对象必须走 serviceaccount token + Kubernetes HTTPS API 或已封装的 native helper；kubectl 只允许在 operator 侧受控 CLI/trans 边界作为 transport/debug 包装，不得进入正式 controller 状态读写链路。
• 一旦发现 CI/CD CLI 被误用且可能写入错误状态、产生伪证据或绕过目标运行面，必须立刻先把用法改成更符合直觉的公开入口并更新本 skill/reference，再继续验证或交付；不要只靠口头记忆、隐藏 flag、手动约定或后续小心来避免复发。内部 in-cluster 模式必须只由目标 k8s Job/Pod 调用，操作者从本机只能用公开入口提交目标侧 Job 或读取目标侧摘要。
• JD01 migrated consumer 的旧手动 publish/debug 命令不得作为正式 closeout 引导；正式 CLI 输出默认必须指向通用 platform-infra pipelines-as-code closeout|status|history。需要保留的旧命令只能标为 debug/test/recovery 单步，且 manual recovery 必须显式说明原因。
• Secret 只通过 YAML sourceRef/targetKey 和受控 CLI 下发；输出只披露 presence/fingerprint。
• 长命令用异步 job 或短轮询；不要长时间挂住 trans/ssh。

何时读取 reference

• PR 自动合并、v0.2/v0.3 lane 差异：读 references/pr-monitor.md。
• 手动触发、定点 PipelineRun/source commit、RBAC/Pipeline/Argo、node-scoped runtime lane：读 references/control-plane.md。
• git-mirror source authority 或 flush：读 references/git-mirror.md。
• AgentRun/HWLAB env reuse、IMAGE_STATUS=reused、ENV_REUSE=hit、skipped,skip=<n> 或 PaC history/status 解释：读 references/env-reuse.md。
• JD01 三运行面 Gitea+PaC 覆盖、旧 branch-follower/Gitea Actions POC 处置和 closeout 顺序：读 references/gitea-pac.md。
• Secret、observability、CI tools image、PipelineRun/PV 清理：读 references/platform-ops.md。
• AgentRun v0.1 或 YAML-only lane 部署：读 references/agentrun.md。
• 三运行面 branch follower 自动跟随、apply/status/run-once/events/logs：读 references/branch-follower.md。