mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: standardize gitea pac cicd architecture

Browse Source
This commit is contained in:
Codex
2026-07-06 15:32:08 +00:00
parent a22ea24ded
commit 79a35183aa
16 changed files with 180 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/unidesk-cicd/SKILL.md
+6 -2
View File
@@ -19,6 +19,7 @@ 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 gitea mirror webhook test --target JD01 --repo unidesk-master --confirm
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 history --target JD01 --limit 10
bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --id <pipelinerun>
bun scripts/cli.ts cicd branch-follower status
@@ -30,6 +31,7 @@ bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel
- PR monitor 与自动合并: [references/pr-monitor.md](references/pr-monitor.md)。
- Tekton/Argo、node-scoped runtime lane、D601 infra bootstrap: [references/control-plane.md](references/control-plane.md)。
- HWLAB/AgentRun git-mirror source authority 与 flush: [references/git-mirror.md](references/git-mirror.md)。
- JD01 Gitea mirror + Pipelines-as-Code 正式架构、三 consumer 覆盖矩阵和旧入口处置: [references/gitea-pac.md](references/gitea-pac.md)。
- AgentRun/HWLAB env reuse 机制、证据解释和 PaC status/history 观察口径: [references/env-reuse.md](references/env-reuse.md)。
- Secret、observability、platform-infra、CI tools image、PipelineRun 清理和 rollout 补记: [references/platform-ops.md](references/platform-ops.md)。
- AgentRun YAML-only lane、v0.1 兼容入口和 AgentRun git-mirror: [references/agentrun.md](references/agentrun.md)。
@@ -38,9 +40,10 @@ bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel
## 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，迁移 lane 使用 Gitea controlled mirror + immutable snapshot ref。受控命令先在 k8s 内同步/创建不可变 `refs/unidesk/snapshots/.../<commit>` stage ref；build/status/publish 只消费该 snapshot，host worktree、本地 `git fetch/pull`、可变 branch ref 或 Pipeline 内直连 GitHub 都不能作为 authoritative source。
- CI/CD source authority 只能来自 YAML 声明的 Kubernetes 托管 source authority：legacy lane 使用 k8s git-mirror snapshot，JD01 migrated lane 使用 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 `agentrun-jd01-v02`、`sentinel-jd01-v03`、`hwlab-jd01-v03` 的正式 CI/CD closeout 入口是 `platform-infra pipelines-as-code status|history --target JD01`。`cicd branch-follower` 和 `cicd gitea-actions-poc` 对这三者只保留历史/迁移只读用途，不得作为当前交付判断入口。
- 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 迁移 lane 的 GitHub -> Gitea 自动同步必须用 `platform-infra gitea mirror webhook apply|status|test`。该路径是单向同步，只更新 Gitea branch 和 immutable snapshot ref；不得引入 Gitea -> GitHub 回写、轮询 fallback 或第二套状态存储。
- 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 带入运行面。
@@ -68,6 +71,7 @@ bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel
- 手动触发、定点 PipelineRun/source commit、RBAC/Pipeline/Argo、node-scoped runtime lane：读 [references/control-plane.md](references/control-plane.md)。
- git-mirror source authority 或 flush：读 [references/git-mirror.md](references/git-mirror.md)。
- AgentRun/HWLAB env reuse、`IMAGE_STATUS=reused`、`ENV_REUSE=hit`、`skipped,skip=<n>` 或 PaC history/status 解释：读 [references/env-reuse.md](references/env-reuse.md)。
- JD01 三运行面 Gitea+PaC 覆盖、旧 branch-follower/Gitea Actions POC 处置和 closeout 顺序：读 [references/gitea-pac.md](references/gitea-pac.md)。
- Secret、observability、CI tools image、PipelineRun/PV 清理：读 [references/platform-ops.md](references/platform-ops.md)。
- AgentRun v0.1 或 YAML-only lane 部署：读 [references/agentrun.md](references/agentrun.md)。
- 三运行面 branch follower 自动跟随、`apply/status/run-once/events/logs`：读 [references/branch-follower.md](references/branch-follower.md)。
.agents/skills/unidesk-cicd/references/branch-follower.md
+10 -5
View File
@@ -2,11 +2,16 @@
SPEC: PJ2026-01060703 CI/CD branch follower draft-2026-07-03-p0-branch-follower
## Retired Scope
For JD01 `agentrun-jd01-v02`, `sentinel-jd01-v03` and `hwlab-jd01-v03`, branch-follower is retired as a delivery authority. The current architecture is Gitea mirror + Pipelines-as-Code + Tekton + Argo; use [gitea-pac.md](gitea-pac.md) for closeout commands and coverage.
The commands below remain historical/migration diagnostics. They must not be used to decide current delivery success for the three migrated JD01 consumers.
## Entrypoints
```bash
bun scripts/cli.ts cicd branch-follower plan
bun scripts/cli.ts cicd branch-follower apply --confirm --wait
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
@@ -21,7 +26,7 @@ bun scripts/cli.ts cicd branch-follower logs --follower <id>
bun scripts/cli.ts cicd branch-follower gate --follower hwlab-jd01-v03 --gate control-plane-refresh --source-commit <sha> --confirm --json
```
`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.
Historically, `apply --confirm --wait` deployed the K8s controller and `run-once --confirm --wait` was the manual trigger and closeout path. For the migrated JD01 consumers this is no longer the formal delivery path. `status`, `events`, `logs` and `debug-step` are retained only to inspect or retire old state.
`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:
@@ -105,11 +110,11 @@ Timeout, TTL, retry/backoff, reconcile interval and end-to-end budget values mus
## First Followers
- `hwlab-jd01-v03`: follows `pikasTech/HWLAB@v0.3`, adapter `hwlab-node-runtime`, native trigger `Tekton PipelineRun -> Argo Application closeout -> runtime Deployment sourceCommit readiness`.
- `agentrun-jd01-v02`: historical first follower only. This lane has migrated to Gitea webhook -> Pipelines-as-Code -> Tekton -> GitOps/Argo -> runtime readiness; do not re-enable branch-follower, act_runner or custom trigger fallback for it. Current operation lives in `config/platform-infra/gitea.yaml`, `config/platform-infra/pipelines-as-code.yaml` and [agentrun.md](agentrun.md).
- `hwlab-jd01-v03`: historical follower only. This lane has migrated to Gitea webhook -> Pipelines-as-Code consumer `hwlab-jd01-v03` -> Tekton -> GitOps/Argo -> runtime readiness; do not re-enable branch-follower, Gitea Actions, act_runner or custom trigger fallback for it.
- `agentrun-jd01-v02`: historical first follower only. This lane has migrated to Gitea webhook -> Pipelines-as-Code -> Tekton -> GitOps/Argo -> runtime readiness; do not re-enable branch-follower, act_runner or custom trigger fallback for it. Current operation lives in `config/platform-infra/gitea.yaml`, `config/platform-infra/pipelines-as-code.yaml`, [gitea-pac.md](gitea-pac.md) and [agentrun.md](agentrun.md).
- `web-probe-sentinel-master`: historical follower only. This lane has migrated to Gitea webhook -> Pipelines-as-Code consumer `sentinel-jd01-v03` -> Tekton publish -> GitOps/Argo -> runtime readiness; do not re-enable branch-follower, Gitea Actions, act_runner or custom fallback for it.
These entries describe the initial production set and migration history. HWLAB still runs on JD01 through branch-follower unless YAML changes; AgentRun JD01 v0.2 and Web 哨兵 JD01 now use the PaC/Gitea path.
These entries describe the initial production set and migration history. Current JD01 closeout for all three consumers uses the PaC/Gitea path.
## Reuse And Mirror Contract
.agents/skills/unidesk-cicd/references/gitea-pac.md
+43
View File
@@ -0,0 +1,43 @@
# Gitea + Pipelines-as-Code
JD01 migrated CI/CD uses one formal path:
```text
GitHub push -> Gitea controlled mirror -> Pipelines-as-Code Repository webhook -> Tekton PipelineRun -> GitOps/Argo -> k8s runtime
```
Do not add Gitea Actions, `act_runner`, branch-follower, host worktree, direct GitHub-in-Pipeline, or custom script fallback for the migrated JD01 consumers. Gitea Actions material under `config/cicd-gitea-actions-poc.yaml` is archived read-only POC context only.
## Source Of Truth
- Gitea source authority, GitHub webhook bridge, public exposure and source snapshots: `config/platform-infra/gitea.yaml`.
- PaC controller, Repository CRs, consumer parameters, Tekton pipeline names and Argo applications: `config/platform-infra/pipelines-as-code.yaml`.
- Historical snapshot prefixes containing `gitea-actions` are retained only for existing refs. They do not mean Gitea Actions is the active trigger architecture.
## Coverage Matrix
| Consumer | Source | PaC namespace | Pipeline | Argo application | Status |
|---|---|---|---|---|---|
| `agentrun-jd01-v02` | `pikasTech/agentrun@v0.2` | `agentrun-ci` | `agentrun-jd01-v02-ci-image-publish` | `agentrun-jd01-v02` | `platform-infra pipelines-as-code status --target JD01 --consumer agentrun-jd01-v02` |
| `sentinel-jd01-v03` | `pikasTech/unidesk@master` | `devops-infra` | `hwlab-web-probe-sentinel-jd01-pac` | `hwlab-web-probe-sentinel-jd01` | `platform-infra pipelines-as-code status --target JD01 --consumer sentinel-jd01-v03` |
| `hwlab-jd01-v03` | `pikasTech/HWLAB@v0.3` | `hwlab-ci` | `hwlab-jd01-v03-ci-image-publish` | `hwlab-node-v03` | `platform-infra pipelines-as-code status --target JD01 --consumer hwlab-jd01-v03` |
Use `bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --limit 10` for all-consumer trigger, timing and reuse audit. It must read live Gitea Repository CR plus Tekton PipelineRun/TaskRun objects on JD01, aggregate on the target side, and print `READ_ERRORS`.
## Closeout Order
1. `bun scripts/cli.ts platform-infra gitea mirror status --target JD01`
2. `bun scripts/cli.ts platform-infra gitea mirror webhook status --target JD01`
3. `bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01 --consumer <id>`
4. `bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --consumer <id> --limit 10`
5. For ambiguous rows, drill into the PipelineRun with `bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --id <pipelinerun>`.
Do not use `cicd branch-follower status` to decide whether the three migrated JD01 consumers are current. It is historical/migration-only and may contain stale state from before PaC cutover.
## Reuse Interpretation
- AgentRun `IMAGE_STATUS=reused` means the image build was skipped or registry artifact was reused for the same env identity.
- Sentinel `ENV_REUSE=hit` means dependency reuse was available; `cache=hit` is separate BuildKit evidence.
- HWLAB `skipped,skip=<n>` means service-level artifact planning skipped reusable builds; inspect the PipelineRun detail when deciding which service changed.
Missing reuse text is not proof of a failed reuse path. Check the consumer type and PipelineRun detail first.
.agents/skills/unidesk-cicd/references/platform-ops.md
+1 -1
View File
@@ -46,7 +46,7 @@ bun scripts/cli.ts platform-infra wechat-archive plan|apply|status|validate|pull
bun scripts/cli.ts platform-infra wechat-archive wcf-host-status|collector-plan|collector-apply|collector-status
```
`platform-infra` 是 UniDesk 运维的平台基础设施控制面；新增平台服务优先进入该命名空间或对应 YAML 声明目标，旧 `devops-infra` 只作为渐进迁移来源。Sub2API 日常部署、Codex pool、FRP 暴露、master `~/.codex` 配置、验收和排障统一使用 `$unidesk-sub2api`。Gitea mirror 和 Pipelines-as-Code 是迁移后的 CI source/trigger 平台服务，source-of-truth 分别是 `config/platform-infra/gitea.yaml` 和 `config/platform-infra/pipelines-as-code.yaml`；PaC status 是 migrated lane closeout 入口，PaC history 是触发/耗时/env reuse 审计入口，默认输出必须包含 `READ_ERRORS` 并在目标 node 聚合，不能把读取失败或 namespace 过大误报为空表成功。不用 Gitea Actions、act_runner、branch-follower 或自维护脚本兜底。`agentrun-jd01-v02` 是默认 consumer；哨兵使用 `--consumer sentinel-jd01-v03` 查看 PaC/Tekton/Argo/env reuse 证据。WeChat archive 是 platform-infra 的 YAML-first 工作流入口；只读 collector 的副本、镜像、WCF host、端口和版本 pin 都以 YAML 为准。
`platform-infra` 是 UniDesk 运维的平台基础设施控制面；新增平台服务优先进入该命名空间或对应 YAML 声明目标，旧 `devops-infra` 只作为渐进迁移来源。Sub2API 日常部署、Codex pool、FRP 暴露、master `~/.codex` 配置、验收和排障统一使用 `$unidesk-sub2api`。Gitea mirror 和 Pipelines-as-Code 是 JD01 migrated CI source/trigger 平台服务，source-of-truth 分别是 `config/platform-infra/gitea.yaml` 和 `config/platform-infra/pipelines-as-code.yaml`；正式架构和三 consumer 矩阵见 [gitea-pac.md](gitea-pac.md)。PaC status 是 migrated lane closeout 入口，PaC history 是触发/耗时/env reuse 审计入口，默认输出必须包含 `READ_ERRORS` 并在目标 node 聚合，不能把读取失败或 namespace 过大误报为空表成功。不用 Gitea Actions、act_runner、branch-follower 或自维护脚本兜底。`agentrun-jd01-v02` 是默认 consumer；哨兵使用 `--consumer sentinel-jd01-v03`，HWLAB 使用 `--consumer hwlab-jd01-v03` 查看 PaC/Tekton/Argo/env reuse 证据。WeChat archive 是 platform-infra 的 YAML-first 工作流入口；只读 collector 的副本、镜像、WCF host、端口和版本 pin 都以 YAML 为准。
## CI Tools Image