多环境配置文件必须与分支硬绑定，否则会导致配置漂移、回滚失效和上线出错；正确做法是每个环境对应独立配置目录且路径显式含环境标识，禁止非main分支修改prod配置，ci须校验分支与配置路径匹配性。
多环境配置文件必须与分支硬绑定，否则配置会漂移、回滚失效、上线出错——这不是规范建议，而是生产事故的常见根因。
配置文件不能跨分支复用
常见错误是把 application-prod.yml 提交到 feature/login 分支里测试，结果该文件被误合入 develop，导致测试环境加载了生产配置。更隐蔽的是：同一份 application.yml 通过 Maven profile 切换环境，但 profile 名称未随分支隔离（比如所有分支都用 -Pproduction），CI 脚本又没校验当前分支，build 阶段就可能用错 profile。
- 正确做法：每个环境对应独立配置目录或文件前缀，且路径/命名中显式包含环境标识，如
config/dev/application.yml、config/test/app-config.yaml - 禁止在非
main分支中修改prod相关配置文件；CI 流水线应拒绝feature/*或develop分支向config/prod/目录的 push - Spring Boot 项目中，
spring.profiles.active的值不应硬编码，而应由构建参数注入（如-Dspring.profiles.active=${CI_ENV}），且${CI_ENV}必须从分支名解析得出（如dev分支 →dev，release/2.1→staging）
Kustomize overlay 目录必须按分支映射
当使用 Kustomize 管理 K8s 配置时，overlays/dev、overlays/test、overlays/prod 这些目录本身不是静态快照，而是 CI 触发源。如果 test 环境部署的是 overlays/test，但该目录最近一次变更来自 feature/auth 分支的 PR，而该 PR 并未合入 develop，就会出现「test 环境跑着未集成代码」的诡异状态。
Conventional Commits v1.0.0 分支、工作树命名及提交信息规范，适用于 GitHub 与 GitLab 项目，用于创建分支和命名工作树等场景。
-
overlays/下每个子目录应只接受对应环境分支的更新：例如overlays/dev只响应dev分支 push，overlays/prod只响应main的 tag 推送 - 避免在
overlays/test中写死镜像 tag，应使用images:字段动态替换，且替换值由 CI 变量传入（如IMAGE_TAG: $CI_COMMIT_SHORT_SHA） - Arco CD 或 Flux 等 GitOps 工具必须配置
targetRevision为具体分支名（如dev），而非HEAD—— 否则它会自动同步最新 commit，绕过分支控制逻辑
Git 钩子和 CI 脚本必须校验配置路径合法性
光靠人工约定“别乱改 prod 配置”没用。实际中，90% 的配置误操作发生在开发者本地 commit 时没意识到自己改的是生产路径，或者 CI 脚本用 git diff --name-only HEAD^ 检查变更范围，却漏掉了新添加的 config/prod/secrets.yaml。
- pre-commit 钩子应检查：若当前分支不是
main或hotfix/*，则禁止向config/prod/和overlays/prod/写入任何文件 - CI 脚本中用
git diff --name-only $CI_MERGE_REQUEST_TARGET_BRANCH_NAME...$CI_COMMIT_SHA获取本次 MR 影响的文件列表（GitHub Actions 用${{ github.event.pull_request.base.ref }}），再过滤是否含敏感路径 - 对 YAML 文件做基础语法校验（如用
yamllint）只是底线，真正关键的是校验字段语义：比如replicas在prod中不能小于 2，这类规则需在 CI 中用jq或自定义脚本断言
最易被忽略的一点：配置文件的加密密钥（如 SOPS 加密用的 age key）不能随配置一起存进仓库，而应通过 CI secret 注入解密过程；否则一旦分支策略松动，密钥就可能泄露到非生产分支的工作树中。
