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

name, description

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

UniDesk HWLAB G14 CI/CD CLI

HWLAB G14 的 PR → CI → CD 控制面和运维入口，统一通过 bun scripts/cli.ts hwlab g14 ... 管理。

固定入口前缀: cd /root/unidesk && bun scripts/cli.ts hwlab g14 ...

---

PR 监控与自动合并

G14 主线

bun scripts/cli.ts hwlab g14 monitor-prs \
  [--lane g14|v02] [--once] [--dry-run] \
  [--interval-seconds N] [--max-cycles N] [--timeout-seconds N]

后台 worker 监控 pikasTech/HWLAB 的 open PR → preflight → 自动合并 → 观察 CI/CD 直到 DEV Synced/Healthy。成功 rollout 后自动追加指挥简报。状态指针按用途分离（latest-monitor-job.json / latest-once-job.json 等）。

v0.2 lane

bun scripts/cli.ts hwlab g14 monitor-prs --lane v02 [--once] [--dry-run]

只监控 base=v0.2 的 PR。CD 采用 latest-only：旧 PipelineRun 不取消不等待，stale commit 以 superseded/no-op 收口。合并后在原 PR 下追加语义化状态评论（含起止时间、source commit、PipelineRun、targetValidation、git mirror 状态）。

v0.3 lane

bun scripts/cli.ts hwlab g14 monitor-prs --lane v03 [--once] [--dry-run]

只监控 base=v0.3 的 PR。ready PR 经 UniDesk gh pr merge 合并后触发 runtime lane CD，检查 PipelineRun、Argo、hwlab-v03 runtime public probes 和 Git mirror flush，并对失败 check、冲突、CD failure/timeout 创建或更新 failure issue。

---

控制面（Tekton/Argo）

状态查询

# 最新 head
bun scripts/cli.ts hwlab g14 control-plane status --lane v02

# 定点 PipelineRun
bun scripts/cli.ts hwlab g14 control-plane status \
  --lane v02 --pipeline-run hwlab-v02-ci-poll-<short-sha>

# 定点 source commit
bun scripts/cli.ts hwlab g14 control-plane status \
  --lane v02 --source-commit <full-sha>

定点 status 输出 targetValidation.state=passed|superseded，只检查指定 target 的证据。

手动触发

bun scripts/cli.ts hwlab g14 control-plane trigger-current \
  --lane v02|v03 [--dry-run|--confirm]

从 /root/hwlab-v02-cicd.git 解析当前 origin/v0.2 full SHA，创建 commit-pinned PipelineRun。confirmed trigger 创建异步 job 并立即返回 job.id。

应用 RBAC/Pipeline/Argo

bun scripts/cli.ts hwlab g14 control-plane apply --lane v02 [--dry-run|--confirm]

server-side apply v02 的 Tekton RBAC、Pipeline 和 Argo Application。

---

Git Mirror

bun scripts/cli.ts hwlab g14 git-mirror status
bun scripts/cli.ts hwlab g14 git-mirror apply [--dry-run|--confirm]
bun scripts/cli.ts hwlab g14 git-mirror sync [--dry-run|--confirm]
bun scripts/cli.ts hwlab g14 git-mirror flush [--dry-run|--confirm]

• apply: 渲染并 apply devops-infra/git-mirror.yaml
• sync: 把当前配置声明的 GitHub refs 拉入本地 mirror
• flush: 把本地 lane GitOps ref 快进推回 GitHub

PipelineRun gitops-promote 如果报 git mirror 控制面漂移、refs 不一致或 flush/publish 未完成，优先按当前 devops-infra/git-mirror.yaml 收敛：先 git-mirror apply --confirm，再 git-mirror sync --confirm --wait，然后用 control-plane cleanup-runs --pipeline-run <failed-run> --confirm 受控清理失败 PipelineRun 后重试。旧 branch/path allowlist gate 已删除，不要恢复旧 hook、直接 kubectl delete、手工 patch pod 内 hook 或绕过 flush。

手动 trigger closeout 不能只看 PipelineRun Completed。必须继续查 control-plane status --pipeline-run <name> 和 git-mirror status；若 pendingFlush=true，执行 git-mirror flush --confirm --wait 到 githubInSync=true。

---

Secret 管理

# 查看
bun scripts/cli.ts hwlab g14 secret status --lane v02 \
  --name hwlab-v02-openfga|hwlab-v02-master-server-admin-api-key

# 确保
bun scripts/cli.ts hwlab g14 secret ensure --lane v02 \
  --name hwlab-v02-master-server-admin-api-key [--dry-run|--confirm]

# 删除废弃 Secret
bun scripts/cli.ts hwlab g14 secret delete --lane v02 \
  --name <obsolete-secret> [--dry-run|--confirm]

---

运行时迁移

bun scripts/cli.ts hwlab g14 control-plane runtime-migration \
  --lane v02 [--dry-run|--confirm]

通过 deployment/hwlab-cloud-api 容器内 migration CLI 执行。

---

Observability

bun scripts/cli.ts hwlab g14 observability status|apply|query|targets|boundary|closeout \
  [--lane v02] [--promql <expr>] [--expect-count N] [--expect-value V] [--dry-run|--confirm]

管理 G14 Prometheus 基础设施和 HWLAB v0.2 监控 closeout。

---

Platform Infra / Sub2API

bun scripts/cli.ts platform-infra sub2api plan|apply|status|validate
bun scripts/cli.ts platform-infra sub2api codex-pool plan|sync|validate|expose|configure-local

• platform-infra 是 G14 k3s 上 UniDesk 运维的平台基础设施 namespace；新增平台服务优先进入该 namespace，旧 devops-infra 只作为渐进迁移来源。
• Sub2API 的日常部署、Codex pool、FRP 暴露、master ~/.codex 配置、验收和排障统一使用 $unidesk-sub2api（UniDesk 仓库 .agents/skills/unidesk-sub2api/SKILL.md）。
• UniDesk 仓库 docs/reference/platform-infra.md 只保留开发边界、YAML-first 真相和探针口径，不重复日常操作手册。

---

CI Tools Image

bun scripts/cli.ts hwlab g14 tools-image status
bun scripts/cli.ts hwlab g14 tools-image build \
  --name ci-node-tools --tag <tag> \
  [--dockerfile deploy/ci/hwlab-ci-node-tools.Dockerfile] [--dry-run|--confirm]

在 G14 host 构建并 push 到本地 registry。

---

PipelineRun 清理

# 清理已完成 PipelineRun
bun scripts/cli.ts hwlab g14 control-plane cleanup-runs \
  --lane v02|g14|all [--min-age-minutes N] [--limit N] [--dry-run|--confirm]

# 补充清理 Released PV
bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs \
  --lane all [--limit N] [--dry-run|--confirm]

---

手动补记 rollout

bun scripts/cli.ts hwlab g14 record-rollout --pr <number> --source-commit <sha>

手动补记 CI/CD 耗时、TaskRun 指标和语义化 changelog 到指挥简报。

---

AgentRun v0.1 控制面

bun scripts/cli.ts agentrun control-plane status \
  [--dry-run|--confirm]
bun scripts/cli.ts agentrun control-plane trigger-current \
  [--dry-run|--confirm]
bun scripts/cli.ts agentrun control-plane refresh \
  [--dry-run|--confirm]
bun scripts/cli.ts agentrun control-plane cleanup-runs \
  [--min-age-minutes N] [--limit N] [--dry-run|--confirm]
bun scripts/cli.ts agentrun control-plane cleanup-released-pvs \
  [--limit N] [--dry-run|--confirm]

• status: 只读汇总 source commit、PipelineRun、Argo、manager image、git mirror 和 aligned 结论
• trigger-current: 快进 G14:/root/agentrun-v01 → mirror sync → 创建 agentrun-v01-ci-<short12> PipelineRun
• refresh: Argo hard refresh（不 patch runtime workload）
• cleanup-runs: 只清理 agentrun-ci 中已完成 PipelineRun + 临时 PVC；不清理 agentrun-v01 runtime runner Job/Pod/Secret
• cleanup-released-pvs: 回收 Released PV

AgentRun control-plane status 的 compact JSON 关键字段在 .data.sourceCommit、.data.expectedPipelineRun、.data.runtimeAlignment、.data.gitMirror.summary 等位置，不要假设存在 .data.status。触发部署后如果 GitOps 已 promotion 但 git mirror pendingFlush=true，先执行 bun scripts/cli.ts agentrun git-mirror flush --confirm --wait，再 control-plane refresh --confirm，最后用 control-plane status --full 证明 runtimeAlignment.localHeadMatchesOrigin=true、syncedToGitopsLatest=true、managerSourceMatchesExpected=true。

AgentRun v0.1 Git Mirror

bun scripts/cli.ts agentrun git-mirror status [--full|--raw]
bun scripts/cli.ts agentrun git-mirror sync [--dry-run|--confirm] [--wait]
bun scripts/cli.ts agentrun git-mirror flush [--dry-run|--confirm] [--wait]

• status: 返回 localV01/githubV01/localGitops/githubGitops/pendingFlush/githubInSync
• sync: 拉取 GitHub v0.1 + v0.1-gitops refs
• flush: 推送本地 v0.1-gitops → GitHub

与 HWLAB v0.2 mirror 共用 devops-infra 服务和 cache PVC。