From 047bce642cb6cdf619b6ba152ee5992a3526fe06 Mon Sep 17 00:00:00 2001 From: "xiaobing.wang" Date: Mon, 11 May 2026 14:35:40 +0800 Subject: [PATCH] docs: tighten gitops ci yq rules --- gitops-app-onboarding/SKILL.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/gitops-app-onboarding/SKILL.md b/gitops-app-onboarding/SKILL.md index 41796b3..309b6b0 100644 --- a/gitops-app-onboarding/SKILL.md +++ b/gitops-app-onboarding/SKILL.md @@ -121,7 +121,7 @@ CI 导出结果固定为： 要求： -- 运行在分支和 MR 上 +- 运行在分支和 MR 上，打 `vX.Y.Z` 发布 tag 时不运行 test job - 安装当前语言栈的最小依赖 - 只有检测到私有 Git 依赖时才补齐认证；否则不要引入 `.netrc` - 使用项目原生测试入口 @@ -183,14 +183,17 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： - 不要在 CI 脚本里用 Python 临时解析或改写 YAML；优先使用 `yq`、`helm`、`git`、`install`、`mkdir`、`cp`、`rsync` 这类明确的 CLI - 修改 `Chart.yaml` 的 `version` / `appVersion` 使用 `yq -i`，不要用 Python heredoc 或内联脚本 -- 修改 Argo CD `Application` 的 `targetRevision` 使用 `yq -i` 定位字段，避免用脆弱的 `sed` 跨行替换 +- 修改 Argo CD `Application` 的 `targetRevision` 时，按当前平台的 `spec.sources` 多 source 结构定位当前 chart source；推荐使用类似 `(.spec.sources[] | select(.chart == strenv(CHART_NAME))).targetRevision = strenv(VERSION)` 的简单 yq selector +- yq 表达式中通过 `strenv(...)` 读取的变量必须先 `export`，例如 `export VERSION="${CI_COMMIT_TAG#v}"`；不要只做 shell 局部赋值 +- CI 中通过 `apk add yq` 安装的 yq 只使用已验证的简单表达式；不要为了兼容 `.spec.source` 单 source 生成 `if ... then ... elif ... else ... end` 这类条件表达式 - 对 CI 文件做合法性自检时，至少能用 `yq e '.' .gitlab-ci.yml` 验证 YAML 语法；如果环境有 GitLab CI lint 工具或 API，再补充 GitLab 语义校验 - `.gitlab-ci.yml` 中的多行 shell 逻辑保持最小化；复杂到需要编程语言脚本时，优先把脚本提交到仓库中的可审查文件，而不是在 CI YAML 里塞内联程序 禁止： - 在 `.gitlab-ci.yml` 中嵌入 `python - <<'PY'`、`python -c` 或临时 Python 脚本来改 YAML -- 用字符串替换方式盲改 `application.yaml` 中所有 `targetRevision` +- 用字符串替换方式盲改 `application.yaml` 中所有 `targetRevision`，或生成兼容 `.spec.source` 单 source 的 yq 分支表达式 +- 在使用 yq `strenv(...)` 前只设置局部变量但不 `export` ### package-chart job @@ -233,7 +236,7 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： 4. 保留已有的 `releases//manifests/kustomization.yaml` 与 `releases//manifests/db-secret.yaml` 5. 将 `deploy/release/secret.yaml` 物化为 `releases//manifests/secret.yaml` 6. 替换 `releases//metadata.yaml` 中的 `__VERSION__`；只有第三方镜像、非业务版本字段或明确需要的环境配置才允许替换 `releases//values.yaml` 中的 `__VERSION__` -7. 用 `yq -i` 更新 `apps//application.yaml` 中当前应用 chart source 的 `targetRevision`，只改当前应用的 chart source +7. 用简单 yq selector 更新 `apps//application.yaml` 中当前应用 chart source 的 `targetRevision`，只改当前应用的 chart source 8. 只有存在 diff 时才提交并推送 `main` 禁止： @@ -493,6 +496,7 @@ Chart 必须反映应用的真实运行架构。 - 接入文件齐全 - `.gitlab-ci.yml` YAML 语法合法，不包含用于改 YAML 的内联 Python - `.gitlab-ci.yml` 包含 test、组件级独立镜像构建、Chart 发布、GitOps 同步 +- test job 不在 `vX.Y.Z` 发布 tag 上运行 - 多服务应用的业务镜像不是由一个串行 `build-images` job 统一构建；每个自建镜像可被 GitLab 独立调度和重试 - `package-chart` 通过 `needs:` 等待所有必要镜像构建成功 - `update-gitops-repo` 通过 `needs:` 依赖 `package-chart` 成功 @@ -503,7 +507,8 @@ Chart 必须反映应用的真实运行架构。 - 如果 Dockerfile 原本使用 Docker Hub 源，已切换到 `registry-mirrors.dev.in.chaitin.net`，且未误改其他非 Docker Hub 镜像源 - 如果 Dockerfile 中使用 `apk`，已切换到中科大源 - GitOps update job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git` -- GitOps update job 用 `yq` 精确更新当前应用 chart source 的 `targetRevision` +- GitOps update job 用多 source yq selector 精确更新当前应用 chart source 的 `targetRevision`，且不包含单 source 兼容分支 +- GitOps update job 中被 yq `strenv(...)` 读取的变量已提前 `export` - CI 中没有直接调用 Argo - 只使用 `deploy.baizhi.cloud` 与 `registry.baizhi.cloud` - 没有使用不安全的 registry 访问方式 @@ -541,6 +546,8 @@ Chart 必须反映应用的真实运行架构。 - 多个服务镜像塞进一个串行 build job，导致无法并行构建、无法单独重试、失败定位困难 - `update-gitops-repo` 没有依赖 `package-chart`，GitOps 仓库先于 Chart 推送被更新 - 在 `.gitlab-ci.yml` 中用 Python heredoc 临时改 `Chart.yaml`、release values 或 `application.yaml` +- yq 使用 `strenv(VERSION)`，但 CI 脚本只写 `VERSION="${CI_COMMIT_TAG#v}"` 而没有 `export VERSION="${CI_COMMIT_TAG#v}"` +- 为当前平台的 Application 更新逻辑生成 `.spec.sources` / `.spec.source` 双结构兼容表达式，导致 `apk add yq` 安装的 yq 解析失败 - `argocd.argoproj.io/sync-wave` 拼错为 `rgocd.argoproj.io/sync-wave`，或把依赖方放在被依赖资源之前 - 只给 Chart 模板资源设计 wave，却遗漏 `releases//manifests/db-secret.yaml`、`secret.yaml`、pull secret 等 release manifests，导致 migrate Job 先于 Secret 执行 - 不顾平台约定把 `registry-pull-secret`、`platform-shared-secrets` 等平台托管资源改成其他 wave；正确做法是保持它们在 `"-1"`，应用资源围绕 `"-1"` 排序