feat: add branch follower debug step
This commit is contained in:
Codex
@@ -16,6 +16,7 @@ bun scripts/cli.ts hwlab g14 control-plane trigger-current --lane v02 --confirm
|
||||
bun scripts/cli.ts hwlab g14 git-mirror status --lane v02
|
||||
bun scripts/cli.ts agentrun control-plane status
|
||||
bun scripts/cli.ts cicd branch-follower status
|
||||
bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step state-read
|
||||
```
|
||||
|
||||
按职责读取拆分后的 reference：
|
||||
@@ -42,6 +43,7 @@ bun scripts/cli.ts cicd branch-follower status
|
||||
- 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 命令才能完成一次交付。
|
||||
- 触发或验收 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，不要通过反复推小提交触发整条自动跟随大回环来定位同一问题。
|
||||
- CI/CD 验证、测试和性能度量必须在目标 NODE/k8s 内执行，尤其是 branch-follower、Tekton/Argo、runtime reuse/env reuse、git mirror 和 runtime-ready 相关改动；不要在 master/local host 跑 test 或用本地验证结果替代目标运行面证据。本机只用于源码阅读、编辑和必要静态语法检查，正式收敛结论必须来自目标 NODE 计算出的短摘要。
|
||||
- 一旦发现 CI/CD CLI 被误用且可能写入错误状态、产生伪证据或绕过目标运行面，必须立刻先把用法改成更符合直觉的公开入口并更新本 skill/reference，再继续验证或交付；不要只靠口头记忆、隐藏 flag、手动约定或后续小心来避免复发。内部 in-cluster 模式必须只由目标 k8s Job/Pod 调用，操作者从本机只能用公开入口提交目标侧 Job 或读取目标侧摘要。
|
||||
- Secret 只通过 YAML sourceRef/targetKey 和受控 CLI 下发；输出只披露 presence/fingerprint。
|
||||
|
||||
@@ -11,12 +11,25 @@ bun scripts/cli.ts cicd branch-follower status
|
||||
bun scripts/cli.ts cicd branch-follower status --live
|
||||
bun scripts/cli.ts cicd branch-follower run-once --all --dry-run
|
||||
bun scripts/cli.ts cicd branch-follower run-once --follower <id> --confirm --wait
|
||||
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step state-read
|
||||
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step status-read
|
||||
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step decide
|
||||
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step state-write --confirm
|
||||
bun scripts/cli.ts cicd branch-follower events --follower <id>
|
||||
bun scripts/cli.ts cicd branch-follower logs --follower <id>
|
||||
```
|
||||
|
||||
`apply --confirm --wait` is the one-command deploy/update entry for the K8s controller. `status` is the default intermediate-state query. `status --live` and local `run-once` submit a bounded K8s reconcile Job; the Job performs all source, Tekton, Argo and runtime reads inside the cluster and may write only the compact state summary. `events` and `logs` are read-only drill-downs for the same Kubernetes-native state. `run-once --confirm --wait` is the manual one-command trigger and closeout path.
|
||||
|
||||
`debug-step` is the required single-step troubleshooting entry before changing branch-follower code for repeated CI/CD convergence issues. It runs in a bounded target-side Job when called from the operator host, and uses the same controller modules as the real flow:
|
||||
|
||||
- `state-read`: read only the compact ConfigMap state, value bytes, resourceVersion and `_updatedAt`.
|
||||
- `status-read`: read native source/Tekton/Argo/runtime status without triggering adapters.
|
||||
- `decide`: run the decision function in dry-run mode without triggering adapters or writing state.
|
||||
- `state-write --confirm`: patch the stored follower state back through the normal ConfigMap write helper and report before/after resourceVersion; this is for isolating state write failures, not for normal rollout.
|
||||
|
||||
Do not debug the same state/read/write problem by repeatedly pushing empty or tiny source commits to drive the full automatic follower loop.
|
||||
|
||||
## Source Authority
|
||||
|
||||
- Follower decisions must not read host source worktrees, target dev directories, `.worktree/*`, local git state, or direct GitHub branch refs.
|
||||
@@ -67,6 +80,8 @@ Default `status` output must show follower id, phase, adapter, source branch + o
|
||||
|
||||
Stage timing must be queryable through normal CLI output, not only raw JSON. `status` and `run-once` print a bounded `STAGE TIMINGS` table with `total`, `status-read`, git-mirror, Kubernetes Job, PipelineRun, TaskRun, Argo, runtime and closeout rows when available. `followers[].timings` remains available in `--raw`/JSON for machine consumers.
|
||||
|
||||
`run-once` also prints a bounded `STATE WRITES` table whenever it writes follower state. The table must include follower id, write status, before/after ConfigMap resourceVersion, whether timing was preserved, exit code and a short message. Missing write evidence is a visibility defect; use `debug-step --step state-write` before any further full-loop validation.
|
||||
|
||||
`timings.totalSeconds` is the authoritative end-to-end wall-clock measurement for a triggered run: measure from `timings.startedAt` until `timings.finishedAt`, or until query time while closeout is still running. Do not compute total by summing stage rows, because stage rows can overlap, omit external waiting, or be reported by different native objects.
|
||||
|
||||
Do not backfill, infer, or migrate old branch-follower state when historical timing, stage timing, or other observability fields are missing or known to be unreliable. Compatibility starts with future state written by the current controller; old missing data must render as `-`/unknown in CLI output instead of being recovered from unrelated native objects.
|
||||
|
||||
Reference in New Issue
Block a user