docs: tighten gitops ci yq rules

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/<app>/manifests/kustomization.yaml` 与 `releases/<app>/manifests/db-secret.yaml`
 5. 将 `deploy/release/secret.yaml` 物化为 `releases/<app>/manifests/secret.yaml`
 6. 替换 `releases/<app>/metadata.yaml` 中的 `__VERSION__`；只有第三方镜像、非业务版本字段或明确需要的环境配置才允许替换 `releases/<app>/values.yaml` 中的 `__VERSION__`
-7. 用 `yq -i` 更新 `apps/<app>/application.yaml` 中当前应用 chart source 的 `targetRevision`，只改当前应用的 chart source
+7. 用简单 yq selector 更新 `apps/<app>/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/<app>/manifests/db-secret.yaml`、`secret.yaml`、pull secret 等 release manifests，导致 migrate Job 先于 Secret 执行
 - 不顾平台约定把 `registry-pull-secret`、`platform-shared-secrets` 等平台托管资源改成其他 wave；正确做法是保持它们在 `"-1"`，应用资源围绕 `"-1"` 排序