mirrors/pikasTech-agentrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da50a34eef07244b6afaaab1944ae1723b3a8bbd
pikasTech-agentrun/docs/reference/spec-v01-cicd.md
T

13 KiB
Raw Blame History

v0.1 CI/CD 与版本 Lane 规格

本文是 AgentRun v0.1 独立 CI/CD、GitOps、namespace、registry 和发布验收规格。AgentRun 从 v0.1 开始废弃 dev/prod 管理口径，改为按 v0.1、v0.2、v0.3 版本 lane 滚动。

设计目标

  • v0.1 是独立 lane，不复用 agentrun_dev 或 agentrun_prod 作为当前运行面。
  • 每条版本 lane 拥有独立 source branch、source worktree、GitOps branch、runtime namespace、artifact catalog、runtime path、CI pipeline 和发布验收。
  • v0.1 只能部署到 agentrun-v01 namespace；v0.2、v0.3 后续使用自己的 namespace 和 GitOps 路径。
  • CI/CD 必须使用 G14 原生 k3s、纯 Tekton Pipeline/Task/PipelineRun 和 Argo CD；不得引入自定义 runner、CI.json runner、长期自研 poller/reconciler、D601 legacy、临时 clone、手工 Pod patch 或本地镜像作为发布真相。
  • v0.1 的 CD 唯一手写真相源是 source branch 内的 deploy/deploy.json；Tekton 生成的 artifact catalog 和 Argo desired state 必须与 source branch 分离，只写入 v0.1-gitops。
  • 发布证据以 live runtime、Argo desired state、GitOps branch、Tekton 证据和干净 source worktree 顺序判断。

固定命名

对象 v0.1 规格
Source repo git@github.com:pikasTech/agentrun.git
Source branch v0.1
Source worktree G14:/root/agentrun-v01
Worktree root G14:/root/agentrun-v01/.worktree/{task}
Runtime namespace agentrun-v01
GitOps branch v0.1-gitops
Artifact catalog v0.1-gitops:deploy/artifact-catalog.v01.json
Runtime path v0.1-gitops:deploy/gitops/g14/runtime-v01
Tekton namespace agentrun-ci
Tekton Pipeline agentrun-v01-ci-image-publish
Tekton ServiceAccount agentrun-v01-tekton-runner
PipelineRun prefix agentrun-v01-ci-<short12>
Argo CD AppProject argocd/agentrun-v01
Argo CD Application argocd/agentrun-g14-v01

公网入口暂不作为 v0.1 必备规格。若后续需要 UniDesk/HWLAB 跨服务入口，必须在本仓库新增受审查的 ingress/FRP/edge spec，不得临时固化 NodePort、host port、pod IP 或一次性 port-forward。

Bun + TypeScript CI 边界

v0.1 自研代码的 CI/CD 工具链以 Bun + TypeScript 为准。Tekton task 必须在受控容器内安装或使用固定 Bun 运行时，执行依赖安装、类型检查、自测试和镜像构建；不得把 master server、G14 固定 source worktree 或手工 host shell 作为构建机。

G14 依赖拉取和镜像发布沿用 HWLAB 成熟 lane 的运行面假设：PipelineRun.spec.taskRunTemplate.podTemplate.hostNetwork=true 且 dnsPolicy=ClusterFirstWithHostNet。因此 Tekton task 内的 127.0.0.1:10808 指向 G14 host bootstrap proxy，127.0.0.1:5000 指向 G14 host-managed registry；NO_PROXY 必须保留 hyueapi.com、.hyueapi.com、cluster service CIDR、.svc 和 .cluster.local。如果未来改成 cluster Service proxy 或 registry DNS，必须同步更新 Tekton template、render 脚本和本文规格，不得只改某个 PipelineRun 实例。

CI 的最小检查应覆盖：

  • bun install 或等价 frozen lockfile 安装。
  • TypeScript 类型检查。
  • Bun/TS 单元自测试，包括 manager schema、adapter mock、Codex fake app-server stdio client 和 CLI JSON 输出。
  • deploy/deploy.json 与 GitOps render 只读校验。

容器镜像可以直接运行 TS 入口，也可以运行同一 source commit 构建出的 JS artifact；无论选择哪种形式，artifact catalog 必须记录完整 source commit 和 image digest。CI/CD 仍然只允许纯 Tekton + Argo CD，不因 Bun 工具链引入自定义 runner、长期 poller 或源分支生成物提交。

真相源

v0.1 发布真相按以下顺序判断：

  1. Live runtime：agentrun-v01 namespace 中 Deployment/Job/Pod ready、事件、日志和 service health。
  2. Argo desired state：argocd/agentrun-g14-v01 的 revision、sync、health、source branch 和 runtime path。
  3. GitOps branch：v0.1-gitops 中的 deploy/artifact-catalog.v01.json 与 deploy/gitops/g14/runtime-v01/**。
  4. Tekton 执行证据：PipelineRun、TaskRun result、image digest 和 promotion 终态。
  5. 干净 source worktree：G14:/root/agentrun-v01、origin/v0.1、render 脚本、deploy intent 和 --no-write 输出。

旧 master 记忆、/root/agentrun 历史固定目录、agentrun_dev、agentrun_prod、D601 legacy 路径、临时 worktree 或本地容器只能作为线索，不能作为 v0.1 发布通过证据。

Source 与 GitOps 分层

v0.1 source branch 可以包含：

  • 源码、测试、长期参考文档、人写配置和模板。
  • deploy/deploy.json，这是 v0.1 CD 唯一手写真相源。
  • Kubernetes 模板、render 脚本、CI/CD helper 和 catalog schema。

v0.1 source branch 不得跟踪：

  • deploy/artifact-catalog.v01.json。
  • deploy/gitops/g14/runtime-v01/**。
  • Argo 实际消费的 rendered runtime desired state。
  • image digest、publish state、reuse evidence 或 CI 生成 rollout metadata。

v0.1-gitops branch 必须包含：

  • deploy/artifact-catalog.v01.json，记录 image tag、digest、source commit、service identity、publish/reuse 状态。
  • deploy/gitops/g14/runtime-v01/**，作为 Argo CD 消费的 desired state。
  • 必要 generated metadata，但不得包含 Secret 值。

首次初始化时，如果 v0.1-gitops:deploy/artifact-catalog.v01.json 尚不存在，只允许由 v0.1 lane 的正式初始化步骤创建第一版 catalog。不得 fallback 到 master、agentrun_dev、agentrun_prod 或 source branch 生成物。

CD 唯一手写真相源

deploy/deploy.json 是 v0.1 CD 的唯一手写真相源。它只承载人写 runtime intent，不承载任何 CI 构造物。

允许写入 deploy/deploy.json 的内容：

  • service id、组件类型和是否参与 v0.1 runtime。
  • replica、resource request/limit、health path、ports、env key、ConfigMap/SecretRef 名称和 key。
  • runtime namespace、ServiceAccount、RBAC intent、PVC intent、NetworkPolicy intent。
  • Postgres 和 Code Agent provider 的 SecretRef 名称、key 名称与 mount/env intent；Secret 值不在 source 或 GitOps 中出现。
  • public/ingress intent 的声明占位；v0.1 默认不要求公网入口。

禁止写入 deploy/deploy.json 的内容：

  • image tag、image digest、publish status、reuse evidence、PipelineRun id、TaskRun id。
  • GitOps branch revision、Argo sync revision、runtime generated manifest。
  • Secret 值、token、kubeconfig、SSH key 或任何 credential value。

Tekton promotion 可以读取 deploy/deploy.json 来 render runtime desired state，但不得回写 source branch 或修改 deploy/deploy.json。所有自动构造物只允许写入 v0.1-gitops 的 deploy/artifact-catalog.v01.json 和 deploy/gitops/g14/runtime-v01/**。

CI/CD 链路

标准链路如下：

  1. 人工或受控 GitHub/UniDesk 入口为某个 origin/v0.1 source commit 创建 Tekton PipelineRun；触发器可以是 Tekton Triggers 或手动 PipelineRun，但不能是长期自定义 runner。
  2. prepare-source checkout v0.1 source，并从 v0.1-gitops 读取上一版 deploy/artifact-catalog.v01.json。
  3. 原语校验 task 只覆盖文档治理、spec 链接、deploy/deploy.json schema、轻量语法和必要单元测试；旧 dev/prod gate 不进入 lane。
  4. Plan task 读取 deploy/deploy.json 与上一版 artifact catalog，判断 affected/reused services；planner 只能输出 TaskRun result 或临时 workspace 文件，不回写 source。
  5. Affected service 通过 Tekton Task 内的 BuildKit/kaniko/buildah 之一发布到 G14 本地 registry；reused service 复用 catalog digest。不得使用 Docker daemon、DIND 或仓库外自定义 runner。
  6. Promotion task 用 publish results 刷新 deploy/artifact-catalog.v01.json，并用 deploy/deploy.json render deploy/gitops/g14/runtime-v01/**，只推送到 v0.1-gitops。
  7. Argo CD Application agentrun-g14-v01 从 v0.1-gitops:deploy/gitops/g14/runtime-v01 同步到 agentrun-v01。
  8. 验收只观察 agentrun-v01 runtime、Argo revision/sync/health 和对应 service health。

Artifact 与镜像身份

  • v0.1 镜像 tag 使用完整 40 位 source commitId。
  • Runtime manifest 必须使用 digest pin 作为部署身份；G14 本地 registry 对同一 tag 的默认 HEAD 可能返回 Docker schema1 compatibility digest，Tekton 必须用 Accept: application/vnd.docker.distribution.manifest.v2+json 采集 containerd 可直接拉取的 schema2 manifest digest，并在写入 catalog 前按 digest HEAD 验证。
  • Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态。
  • 同一 source commit 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、RBAC 和 runtime config 中，不 bake 进镜像。
  • deploy/deploy.json 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。
  • Source branch 不得因为 promotion 出现自动提交；若发布后 source branch 变化，必须是人工修改源码、测试、文档、模板或 deploy/deploy.json。

Kubernetes 与 Argo 边界

  • agentrun-v01 namespace 只能由 v0.1 GitOps lane 管理。
  • argocd/agentrun-v01 AppProject destination 只能包含 agentrun-v01。
  • argocd/agentrun-g14-v01 source 必须指向 v0.1-gitops:deploy/gitops/g14/runtime-v01，destination 必须是 agentrun-v01。
  • v0.1 Secret、ServiceAccount、RBAC、PVC、ConfigMap 和 runtime config 必须独立命名或 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。
  • agentrun-mgr 和 runner Job 只能通过 spec-v01-secret-distribution.md 定义的 SecretRef 注入 Postgres DSN 和 Codex auth/config 文件；测试 Codex 凭据来自 ~/.codex/auth.json 与 ~/.codex/config.toml 的 Kubernetes Secret projection，不得从 deploy/deploy.json、artifact catalog 或 generated manifest 中读取明文。
  • Postgres DATABASE_URL Secret 必须使用实际创建的数据库名，v0.1 默认为 agentrun_v01；密码或其他 URL credential 必须 URL encode 后写入 DSN。Secret 值不进入 source/GitOps，runtime bootstrap 或 secret-management 流程负责创建与轮换。
  • Codex provider Secret 在 GitOps manifest 中只能表现为 SecretRef 和只读 volume projection；runner Job manifest 还必须包含 writable runtime home，用于把 Secret projection 复制到 CODEX_HOME 后运行 Codex。
  • agentrun_dev 和 agentrun_prod 不得作为 v0.1 namespace、Argo destination、Pipeline target 或验收目标。

手动和热修边界

  • 只读诊断可以通过 UniDesk route G14:k3s 查询 agentrun-v01。
  • 写操作必须走 Tekton PipelineRun、GitOps promotion、Argo CD 或仓库内受控 CLI；不得长期使用手工 kubectl apply/patch/delete 维持运行态。
  • 任何需要临时 live hotfix 的情况，必须先记录 issue/PR，说明原因、影响范围、回滚方式和后续固化路径。
  • 不得在 master server 构建镜像、运行重型测试或把本地 Docker image 当作发布真相。

验收标准

  • G14:/root/agentrun-v01 source worktree 为 v0.1...origin/v0.1 且 clean。
  • AGENTS.md 和 docs/reference/ 不得把 agentrun_dev 或 agentrun_prod 写成 v0.1 当前 namespace、Argo destination、Pipeline target 或验收目标；只允许在废弃说明和历史背景中提及。
  • agentrun-v01 namespace 存在，且 agentrun_dev/agentrun_prod 不参与 v0.1 发布判定。
  • v0.1-gitops branch 和 deploy/gitops/g14/runtime-v01 成为 Argo desired state 来源。
  • deploy/deploy.json 是 CD 唯一手写真相源；source branch 不跟踪 artifact catalog、runtime generated manifests、digest 或 publish state。
  • Tekton/Argo 路径不包含自定义 runner、CI.json runner、长期自研 poller 或 control-plane reconciler。
  • Runtime manifest 使用 digest pin，catalog 记录完整 source commit 与 digest。
  • 发布完成后可通过 G14:k3s 读取 agentrun-v01 Pod ready、service health 和对应 image digest。

规格的实现情况

规格项 状态 说明
v0.1 source branch 已建立 origin/v0.1 存在。
G14:/root/agentrun-v01 source worktree 已建立 固定 source worktree 使用 v0.1 分支。
agentrun-v01 namespace 部分实现 GitOps rendered manifest 已声明 namespace；运行面初始化和 Argo 同步仍需综合联调验收。
v0.1-gitops branch 部分实现 Tekton promotion 已生成 artifact catalog 与 runtime desired state；后续每个 source commit 仍需由 PipelineRun 推进。
纯 Tekton/Argo lane 部分实现 已有 agentrun-ci Pipeline、BuildKit 镜像发布、GitOps promotion 模板和 Argo Application 模板；真实 runtime sync 与综合联调仍需收口。
dev/prod 废弃口径 已定义 本文明确 agentrun_dev 和 agentrun_prod 不作为当前规格目标。
Reference in New Issue View Git Blame Copy Permalink