docs: enforce PR-merge automatic delivery

2026-07-11 08:12:00 +02:00
parent 0e8ffe58d6
commit a7823cf919
8 changed files with 221 additions and 55 deletions
@@ -0,0 +1,15 @@
+# R1.1 任务报告
+
+## 盘点结论
+
+- 来源：https://github.com/pikasTech/unidesk/issues/1755
+- 已识别会误导 migrated consumer 人工补链的旧规则：
+  - 把 `trigger-current` 当作通用交付入口；
+  - 把 `closeout --wait` 放入默认观察顺序与覆盖矩阵；
+  - 在 stale mirror 时引导人工 `REPAIR` 或 mirror sync；
+  - 把“受控 CLI”误解为 PR 合并后仍需执行写命令。
+- 已将 legacy/bootstrap 入口与 PaC migrated consumer 的自动交付边界分开。
+
+## 结论
+
+PaC migrated consumer 的交付不存在合并后人工“下一步”；若链路断开，只能修复自动链。
@@ -0,0 +1,24 @@
+# R1.2 任务报告
+
+## 规则收敛
+
+- 来源：https://github.com/pikasTech/unidesk/issues/1755
+- 唯一正式触发：目标 source branch 的 GitHub PR merge。
+- 唯一正式链路：
+  - GitHub webhook；
+  - Gitea controlled mirror 与 immutable snapshot ref；
+  - Gitea webhook；
+  - PaC；
+  - Tekton；
+  - GitOps/Argo；
+  - runtime 自动滚动。
+- 主代理、子代理与操作者均不得通过 apply、closeout、trigger、sync、flush、人工 PipelineRun 或运行面 patch 补链。
+- 自动链失败时必须修复 owning YAML、controller 或源码，并以修复 PR 合并产生的新事件验收。
+- `status/history/events/logs` 仅在显式故障调查时按需读取，不是交付前置。
+- `closeout` 只保留可选只读历史/诊断兼容能力，不得成为默认观察顺序或代理任务。
+
+## 变更位置
+
+- `.agents/skills/unidesk-cicd/SKILL.md`
+- `.agents/skills/unidesk-cicd/references/gitea-pac.md`
+- `docs/reference/platform-infra.md`
@@ -0,0 +1,19 @@
+# R1.3 任务报告
+
+## 文档合同
+
+- 来源：https://github.com/pikasTech/unidesk/issues/1755
+- 新增 `scripts/src/cicd-pr-merge-auto-delivery-doc-contract.test.ts`。
+- 合同覆盖：
+  - PR merge 唯一触发与完整自动链；
+  - 主/子代理与操作者禁止人工补链；
+  - 故障调查入口只读；
+  - coverage matrix 与按需调查段不得重新引导 `closeout --wait`；
+  - `source-artifact write` 仅限 PR 合并前；
+  - 可调整预算由 owning YAML 声明。
+
+## 验证
+
+- 命令：`bun test scripts/src/cicd-pr-merge-auto-delivery-doc-contract.test.ts`
+- 结果：6 pass，0 fail，40 个断言通过。
+- `git diff --check` 通过。
@@ -0,0 +1,22 @@
+# PR 合并驱动的全自动交付
+
+- 来源：https://github.com/pikasTech/unidesk/issues/1755
+- 范围：长期规则、CI/CD skill 与文档合同。
+- 边界：不执行任何人工 CI/CD 触发、补跑或运行面修改。
+
+
+## R1 [in_progress]
+
+固化 PR 合并驱动的全自动交付与故障修复边界，来源：https://github.com/pikasTech/unidesk/issues/1755，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R1_Task_Report.md)。
+### R1.1 [completed]
+
+盘点并收敛会误导人工触发或补跑的长期规则，引用：https://github.com/pikasTech/unidesk/issues/1755，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R1.1_Task_Report.md)。
+### R1.2 [completed]
+
+更新 CI/CD reference 与 skill，明确 PR merge 唯一触发及自动链故障修复边界，引用：https://github.com/pikasTech/unidesk/issues/1755，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R1.2_Task_Report.md)。
+### R1.3 [completed]
+
+补充轻量文档合同检查，阻止人工交付入口重新成为正式路径，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R1.3_Task_Report.md)。
+### R1.4 [in_progress]
+
+完成静态验证、报告、提交、推送与非草稿 PR，禁止触发或部署 CI/CD，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R1.4_Task_Report.md)。
@@ -23,7 +23,8 @@
 - PaC Repository CR `spec.url` is the URL matcher for incoming Gitea webhook payloads, so `config/platform-infra/pipelines-as-code.yaml#repositories[].url` must use the public Gitea repository URL emitted by Gitea webhooks. Internal ClusterIP/service URLs belong in `cloneUrl` and `params.git_read_url`; putting an internal URL in `spec.url` makes PaC log `cannot find a repository match` and creates no PipelineRun even though the Gitea mirror is current.
 - PaC Repository CR params must use the node-specific Gitea snapshot prefix declared for that consumer, such as `unidesk-master-nc01` for NC01 sentinel. A generic or other-node prefix can make the repository look healthy while fresh pushes cannot close out against the target node source.
 - PaC history is the trigger/timing audit surface for Gitea/PaC-managed lanes. It must query Gitea Repository CR and Tekton PipelineRun/TaskRun live objects on the target node, aggregate there, return Beijing-time display by YAML timezone, expose a detail id for drill-down, and report read errors explicitly; a large namespace or unreadable target object must never be rendered as a successful empty table.
- Formal delivery for a PaC-migrated consumer starts with merging the GitHub PR into that consumer's YAML-declared upstream branch. The GitHub webhook bridge then syncs GitHub to the controlled Gitea mirror and immutable snapshot refs; the Gitea repository push webhook triggers Pipelines-as-Code, which creates the Tekton PipelineRun. Operators must not replace this with `trigger-current`, `webhook-test`, a direct Gitea push, raw PipelineRun creation, or a local Git mirror edit. `webhook-test` is only a connectivity diagnostic.
+- PaC 迁移 consumer 的目标 source branch GitHub PR merge 是唯一正式交付触发事件。合并后必须由 GitHub webhook、Gitea controlled mirror 与 immutable snapshot ref、Gitea webhook、PaC、Tekton、GitOps/Argo 自动推进到运行面；主代理、子代理和操作者都不得执行 apply、closeout、trigger、sync、flush、人工 PipelineRun、直接 Gitea push、本地 Git mirror 修改或其他补跑来完成本次交付。`webhook-test` 只是连通性诊断，不得代替真实 PR merge 事件。
+- 自动链不通时必须修复 owning YAML、controller 或源码中的自动链缺陷，并用修复 PR 合并后产生的新自动事件验证；禁止用人工操作制造对齐状态或掩盖故障。`status`、`history`、`events`、`logs` 与单步 debug 入口只在显式调查时按需读取，不是交付前置；`closeout` 仅保留只读兼容能力，不得成为主/子代理的 PR 合并后步骤。任何诊断入口都不得隐式推进交付。
 - `config/platform-infra/pipelines-as-code.yaml` may declare multiple repositories and consumers. JD01 and NC01 both declare AgentRun, Web sentinel and HWLAB consumers; use `cicd status --node <NODE>` for node-level status, `history --target <NODE>` for all-consumer audit, and `status --target <NODE> --consumer <id>` for consumer-scoped closeout. Consumer-scoped status must not mix PipelineRuns or env reuse evidence across repositories.
 - Shared upstream repositories must isolate target-specific `.tekton` files with Repository CR params, currently `node`, and `pipelinesascode.tekton.dev/on-cel-expression`. A NC01 webhook delivery must not create JD01 PipelineRuns in the NC01 cluster, and history drill-down must not attribute the same PipelineRun to multiple consumers.
 - Public Gitea UI may use the YAML-declared HTTPS hostname, but k8s-internal consumers must use the ClusterIP service URL from YAML. Internal CI/Argo/runtime reads must not loop through public DNS/Caddy/FRP, and migrated lanes must not fall back to legacy git-mirror read URLs when the commit exists only in Gitea.