---
name: unidesk-cicd
description: 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 主线

```bash
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

```bash
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

```bash
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）

### 状态查询

```bash
# 最新 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 的证据。

### 手动触发

```bash
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

```bash
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

```bash
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 管理

```bash
# 查看
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]
```

---

## 运行时迁移

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

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

---

## Observability

```bash
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

```bash
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

```bash
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 清理

```bash
# 清理已完成 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

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

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

---

## AgentRun v0.1 控制面

```bash
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

```bash
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。
