# G14 GitOps CI/CD

G14 是 HWLAB 的旁路 DEV 集群目标。G14 CI/CD 必须只作用于 G14 k3s，不接管 D601 生产，不使用 UniDesk Code Queue 作为调度器，也不把 UniDesk backend、provider-gateway 或 microservice proxy 当作 HWLAB runtime。

## 目标模型

- Source of truth：业务版本以 Git source commit 为唯一身份；镜像 tag、OCI labels、runtime annotation 和 Argo CD desired state 都必须记录同一个 source commit。
- CI：Tekton 在 G14 k3s 内运行 `hwlab-g14-ci-image-publish` Pipeline，读取 `CI.json` 命令，按 source commit 构建镜像并推送到 G14 registry。
- Artifact：镜像使用 commit tag，例如 `127.0.0.1:5000/hwlab/hwlab-cloud-api:<shortCommit>`；digest 由 registry 返回，CI report 只作为审计证据，不作为 CD 真相。
- CD：Argo CD 只消费 `deploy/gitops/g14/runtime` 的 Git desired state，不重新构建镜像，不读取 D601 状态，不获取 legacy DEV CD Lease。
- 并行性：不同 source commit 的 CI build 不共享发布锁；并行安全由 immutable commit tag/digest 和 Git desired state 保证。最终运行版本由 Argo CD 当前同步的 Git revision 决定。

## 生成入口

`scripts/g14-gitops-render.mjs` 是 G14 专用转换器：

- 读取 `CI.json`，生成 Tekton Pipeline 和 PipelineRun 样板。
- 读取 `deploy/deploy.json` 与 `deploy/k8s/*`，生成 Argo CD 可消费的 G14 runtime Kustomize path。
- 默认输出到 `deploy/gitops/g14/`。
- 默认 registry prefix 是 `127.0.0.1:5000/hwlab`，用于 G14 单节点 k3s 的 node-local registry。
- 默认 CI/CD proxy 是 G14 本机 `http://127.0.0.1:10808` / `socks5h://127.0.0.1:10808`。Tekton CI step、Docker-in-Docker sidecar 和 publish step 都注入 proxy/no_proxy，保证 npm、Playwright、base image 拉取和 registry push 走 G14 本机代理边界。

常用命令：

```sh
npm run g14:gitops:render -- --source-revision <sourceCommit>
npm run g14:gitops:check
```

## 集群资源

- `hwlab-ci`：registry、Tekton runner RBAC、Pipeline/PipelineRun 所在 namespace。
- `argocd`：Argo CD 控制面和 `hwlab-g14-dev` Application 所在 namespace。
- `hwlab-dev`：HWLAB runtime namespace，由 Argo CD 应用 `deploy/gitops/g14/runtime`。

G14 registry 由 Kubernetes Deployment `hwlab-ci/hwlab-registry` 承载，使用 host network 暴露 `127.0.0.1:5000` 给 k3s/containerd 和 host-network Tekton build pod。旧 host Docker registry 不能与该 Deployment 同时占用 5000 端口。

G14 k3s/containerd 的 Pod 镜像拉取也必须长期使用 G14 本机代理。主机配置记录在 `/root/docs/kubernetes-ops.md`，当前 systemd env 文件是 `/etc/systemd/system/k3s.service.env`。修改代理后需要 `systemctl daemon-reload && systemctl restart k3s`，并确认 `k3s-server` 进程环境中存在 `HTTP_PROXY` / `NO_PROXY`。

## 凭证边界

HWLAB repo 是私有仓库时，Tekton 和 Argo CD 需要各自的 Git SSH Secret。Secret 只能从 G14 本机已有 SSH key 创建，不能写入 Git，不能打印 key 内容。

Tekton 约定 Secret 名称：`hwlab-ci/hwlab-git-ssh`。

Argo CD 约定 repository Secret：`argocd/hwlab-git-ssh`，并带 label `argocd.argoproj.io/secret-type=repository`。

## D601 边界

G14 GitOps manifests 不包含 D601 kubeconfig、D601 node guard、D601 FRP 公网入口或 UniDesk Code Queue 调度入口。D601 仍由既有生产路径维护；G14 GitOps 的安装、PipelineRun、Argo sync 和 registry 操作都不能对 D601 执行 kubectl、docker 或流量切换动作。