GitLab中合并代码后主分支Docker镜像重打标签的问题

我在帮团队搭建GitLab CI流水线的时候，正好遇到过一模一样的问题——MR阶段构建的镜像用提交ID+分支打标，合并到master后死活找不到对应标签来重打latest，折腾了好几个方案，下面给你分享几个经过实际验证的解决思路：

方案1：用GitLab API把镜像标签绑定到合并提交 #

这个方案的核心是在MR流水线的Package阶段，把构建好的镜像标签存为对应提交的临时变量，等合并到master后，直接读取这个变量来重打标签。

具体操作步骤：

1. 首先在GitLab项目里创建一个拥有API权限的访问令牌（比如GITLAB_TOKEN），设置为项目级的protected变量，确保只有流水线能访问。
2. 在MR的Package任务末尾添加脚本，把当前镜像标签存为提交关联变量：

   # 构建镜像标签（和你现有逻辑一致）
   IMAGE_TAG="${CI_COMMIT_SHORT_SHA}-${CI_COMMIT_BRANCH}"
   docker build -t ${IMAGE_NAME}:${IMAGE_TAG} .
   
   # 调用GitLab API创建针对当前提交的变量
   curl --request POST \
     --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
     "https://your-gitlab-instance/api/v4/projects/${CI_PROJECT_ID}/variables" \
     --form "key=SOURCE_IMAGE_TAG" \
     --form "value=${IMAGE_TAG}" \
     --form "protected=false" \
     --form "masked=false" \
     --form "environment_scope=*"
   

3. 在master分支的retag&push任务里，直接读取这个变量完成重打标签：

   docker pull ${IMAGE_NAME}:${SOURCE_IMAGE_TAG}
   docker tag ${IMAGE_NAME}:${SOURCE_IMAGE_TAG} ${IMAGE_NAME}:latest
   docker push ${IMAGE_NAME}:latest
   

4. 可选：在master流水线完成后，添加清理脚本删除临时变量，避免变量堆积：

   curl --request DELETE \
     --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
     "https://your-gitlab-instance/api/v4/projects/${CI_PROJECT_ID}/variables/SOURCE_IMAGE_TAG"
   

优点：精准关联MR构建的镜像，不会出错；缺点：需要维护API令牌权限，额外的变量清理步骤。

方案2：把镜像标签写入合并提交的描述中 #

如果不想用API，也可以利用Git提交消息来传递标签信息——在MR合并时，自动把镜像标签附加到提交描述里，master流水线再从描述中提取标签。

具体操作：

1. 在MR的Test任务通过后，添加脚本调用GitLab API自动合并MR，并在提交消息中加入镜像标签：

   IMAGE_TAG="${CI_COMMIT_SHORT_SHA}-${CI_COMMIT_BRANCH}"
   MERGE_COMMIT_MSG="Merge branch '${CI_COMMIT_BRANCH}' into master\n[IMAGE_TAG: ${IMAGE_TAG}]"
   
   # 调用API合并MR（需要提前获取MR的IID）
   curl --request PUT \
     --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
     "https://your-gitlab-instance/api/v4/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/merge" \
     --form "commit_message=${MERGE_COMMIT_MSG}"
   

2. 关闭MR的手动合并权限，强制所有合并必须通过流水线触发，避免遗漏标签信息。
3. 在master分支的retag&push任务里，提取提交描述中的标签：

   # 从最新的master提交描述中提取镜像标签
   SOURCE_IMAGE_TAG=$(git log -1 --pretty=%B | grep -oP '(?<=IMAGE_TAG: ).*')
   docker pull ${IMAGE_NAME}:${SOURCE_IMAGE_TAG}
   docker tag ${IMAGE_NAME}:${SOURCE_IMAGE_TAG} ${IMAGE_NAME}:latest
   docker push ${IMAGE_NAME}:latest
   

优点：不需要额外存储变量，利用Git原生信息；缺点：依赖提交消息格式，必须强制流水线合并MR。

方案3：简化标签规则，让master流水线可推导标签 #

如果可以调整MR阶段的镜像标签规则，这个方案最省心——把MR的镜像标签简化为唯一的提交ID，因为提交ID在整个仓库中是唯一的，合并到master后，直接通过Git命令获取合并进来的提交ID即可。

具体操作：

1. 修改MR的Package任务，把镜像标签改为仅用提交短ID：

   IMAGE_TAG="${CI_COMMIT_SHORT_SHA}"
   docker build -t ${IMAGE_NAME}:${IMAGE_TAG} .
   docker push ${IMAGE_NAME}:${IMAGE_TAG}
   

2. 在master分支的retag&push任务里，获取合并进来的提交ID：

   # 如果是普通合并，用HEAD^1获取合并进来的提交ID
   # 如果是 squash merge，直接用HEAD（因为squash后MR的提交会被压缩成一个新提交）
   SOURCE_SHA=$(git rev-parse HEAD^1)
   docker pull ${IMAGE_NAME}:${SOURCE_SHA}
   docker tag ${IMAGE_NAME}:${SOURCE_SHA} ${IMAGE_NAME}:latest
   docker push ${IMAGE_NAME}:latest
   

优点：规则简单，不需要任何额外传递逻辑；缺点：如果团队使用squash merge，需要调整获取提交ID的逻辑。

方案4：用Pipeline Artifacts传递标签文件 #

最后一个方案是利用GitLab的流水线工件（Artifacts）来传递标签信息——在MR的Package阶段把标签写入文件并上传为Artifacts，master流水线通过API下载对应MR的Artifacts来读取标签。

具体操作：

1. 在MR的Package任务中，添加标签文件并上传Artifacts：

   IMAGE_TAG="${CI_COMMIT_SHORT_SHA}-${CI_COMMIT_BRANCH}"
   docker build -t ${IMAGE_NAME}:${IMAGE_TAG} .
   docker push ${IMAGE_NAME}:${IMAGE_TAG}
   
   # 写入标签文件并上传
   echo "${IMAGE_TAG}" > image_tag.txt
   

   然后在任务中配置Artifacts：

   artifacts:
     paths:
       - image_tag.txt
     expire_in: 7d
   

2. 在master分支的retag&push任务里，调用API找到对应MR的流水线，下载Artifacts并读取标签：

   # 获取合并提交对应的MR IID（假设提交消息里有!#123这样的MR编号）
   MR_IID=$(git log -1 --pretty=%B | grep -oP '(?<=!#).*')
   # 找到MR的最新流水线ID
   PIPELINE_ID=$(curl --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" "https://your-gitlab-instance/api/v4/projects/${CI_PROJECT_ID}/merge_requests/${MR_IID}/pipelines" | jq -r '.[0].id')
   # 下载Artifacts中的image_tag.txt
   curl --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" "https://your-gitlab-instance/api/v4/projects/${CI_PROJECT_ID}/pipelines/${PIPELINE_ID}/artifacts" -o artifacts.zip
   unzip artifacts.zip
   SOURCE_IMAGE_TAG=$(cat image_tag.txt)
   
   # 重打标签并推送
   docker pull ${IMAGE_NAME}:${SOURCE_IMAGE_TAG}
   docker tag ${IMAGE_NAME}:${SOURCE_IMAGE_TAG} ${IMAGE_NAME}:latest
   docker push ${IMAGE_NAME}:latest
   

优点：利用GitCI原生功能，不需要额外存储变量；缺点：API调用逻辑稍复杂，需要处理MR和流水线的关联关系。

内容的提问来源于stack exchange，提问作者st0ne2thedge