Git分支名结合提交哈希生成Docker镜像标签是最可靠、可追溯的策略，GitLab用CI_COMMIT_BRANCH与CI_COMMIT_SHORT_SHA组合，GitHub用github.head_ref与github.sha组合，避免仅用分支名导致覆盖，确保每次构建唯一可复现。
Git 分支名直接决定 Docker 镜像标签，这是 CI 流水线里最可靠、最易追溯的打包策略。别用 latest，也别靠脚本猜分支，让 CI 系统明确读取 CI_COMMIT_BRANCH 或 GITHUB_HEAD_REF 这类环境变量来生成镜像名。
GitLab CI 中用 CI_COMMIT_BRANCH 构建带分支标签的镜像
GitLab Runner 在每次流水线启动时，会自动注入 CI_COMMIT_BRANCH 变量，值为当前触发流水线的分支名（如 feature/login、release/v2.1）。这个变量可直接用于 docker build 和 docker tag。
- 构建命令中直接引用：
docker build -t myapp:${CI_COMMIT_BRANCH} . - 若分支名含斜杠（如
feature/auth），Docker 标签不支持/，需替换：用${CI_COMMIT_BRANCH//\//-}（Bash 参数扩展）转成feature-auth - 避免在
.gitlab-ci.yml中硬编码分支判断逻辑——分支策略会变，环境变量不会 - 注意：MR 合并流水线中该变量是目标分支（如
main），不是源分支；如需源分支，改用CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
GitHub Actions 里用 GITHUB_HEAD_REF 区分 PR 与 push 场景
GitHub Actions 没有统一的“当前分支”变量，得看触发事件类型：push 用 github.head_ref，pull_request 用 github.head_ref（源分支），而 github.base_ref 是目标分支。直接写死会出错。
- 在
.github/workflows/ci.yml中，用条件判断分流：if: github.event_name == 'push' run: docker build -t myapp:${{ github.head_ref }} . - PR 场景下建议打测试专用标签：
docker build -t myapp:pr-${{ github.event.number }} . -
github.ref是完整 ref 路径（如refs/heads/main），提取分支名要切掉前缀：${{ github.ref_name }}（GitHub Actions v2.290+ 支持） - 不要依赖
git branch --show-current—— runner 环境可能未检出完整历史，结果不可靠
Docker 镜像标签必须包含 Git 提交哈希才真正可复现
仅用分支名打标（如 myapp:main）存在覆盖风险：同一分支多次推送，镜像会被覆盖，丢失历史版本。必须把 CI_COMMIT_SHORT_SHA 或 GITHUB_SHA 加进去。
- 推荐格式：
myapp:${CI_COMMIT_BRANCH}-${CI_COMMIT_SHORT_SHA}（GitLab）或myapp:${{ github.head_ref }}-${{ github.sha }}（GitHub） - 若需语义化标签（如
v1.2.0），应由 Git tag 触发专用流水线，而非分支流水线——tag 是不可变锚点，分支不是 - 镜像仓库（如 Harbor、ECR）默认允许覆盖同名标签；启用“不可覆盖标签”策略后，没哈希的标签会构建失败，反而暴露问题
- CI 日志里务必打印最终镜像名：
echo "Built image: myapp:${CI_COMMIT_BRANCH}-${CI_COMMIT_SHORT_SHA}"
本地调试时如何模拟 CI 的分支环境变量
开发 .gitlab-ci.yml 或 workflow.yml 时，不能等推上去再试。本地用 docker run 模拟 CI 环境最准，别用 source 或 export 手动设变量——少了完整上下文。
- GitLab CI 模拟（Linux/macOS）：
docker run --rm -v $(pwd):/project -w /project -e CI_COMMIT_BRANCH=develop -e CI_COMMIT_SHORT_SHA=abc123 gitlab/dind:latest sh -c "cd /project && docker build -t myapp:develop-abc123 ." - GitHub Actions 模拟更简单：直接在本地执行 workflow 中的 shell 命令，把
${{ github.head_ref }}替换成实际分支名，但注意secrets和actions无法本地运行 - 关键检查点：运行
git status和git rev-parse HEAD确认工作树干净、SHA 正确——CI 环境默认是 clean checkout，本地常有 untracked 文件干扰构建
分支名只是入口，真正决定镜像内容的是那次提交的完整快照。所有构建都应基于明确 commit，而不是“当前分支最新”。否则某天 main 被 force push，你部署的就不是原来那个 main 了。
