配置GitLab CI推送至Azure容器注册表遇「未找到相关标签」问题

核心问题拆解 #

• 镜像标签缺少ACR登录服务器前缀：ACR要求镜像必须以$ACR_LOGIN_SERVER/镜像名:标签格式命名，否则推送时无法匹配对应仓库
• GitLab CI的Job是隔离环境：build阶段构建的镜像不会自动同步到push阶段的Runner，跨Job传递镜像会丢失
• Docker Compose配置中的镜像引用未指向ACR：部署时会找不到对应镜像

修复后的完整配置 #

stages:
  - build-push
  - deploy

variables:
  TAG: $CI_COMMIT_SHORT_SHA
  PROJECT_NAME: project-name
  # 统一ACR镜像前缀，直接复用已配置的CI变量
  ACR_IMAGE_PREFIX: $ACR_LOGIN_SERVER

build-push:
  stage: build-push
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  tags:
    - docker
  before_script:
    - docker login $ACR_LOGIN_SERVER -u $ACR_USERNAME -p $ACR_PASSWORD
  script:
    # 构建时直接使用ACR完整前缀命名镜像
    - docker build --pull --rm -f "backend/Dockerfile" -t $ACR_IMAGE_PREFIX/webapi:$TAG "im_v2/backend"
    - docker build --pull --rm -f "frontend/Dockerfile" -t $ACR_IMAGE_PREFIX/client:$TAG "im_v2/frontend"
    - docker build --pull --rm -f "deploy/gateway/Dockerfile" -t $ACR_IMAGE_PREFIX/gateway:$TAG "im_v2/deploy/gateway"
    # 直接在同一个Job内推送，避免跨环境丢失镜像
    - docker push $ACR_IMAGE_PREFIX/webapi:$TAG
    - docker push $ACR_IMAGE_PREFIX/client:$TAG
    - docker push $ACR_IMAGE_PREFIX/gateway:$TAG
  artifacts:
    paths:
      - deploy/production/docker-compose.yml
  only:
    - /^development.*$/
    - /^deployment.*$/

deploy:
  stage: deploy
  image: mcr.microsoft.com/azure-cli
  script:
    - az login --service-principal --username $AZURE_CLIENT_ID --password $AZURE_CLIENT_SECRET --tenant $AZURE_TENANT_ID
    # 替换Docker Compose中的镜像地址为ACR完整路径
    - sed -i "s|webapi:$TAG|$ACR_IMAGE_PREFIX/webapi:$TAG|g" deploy/production/docker-compose.yml
    - sed -i "s|client:$TAG|$ACR_IMAGE_PREFIX/client:$TAG|g" deploy/production/docker-compose.yml
    - sed -i "s|gateway:$TAG|$ACR_IMAGE_PREFIX/gateway:$TAG|g" deploy/production/docker-compose.yml
    - az webapp config container set --name $AZURE_APP_SERVICE_NAME --resource-group $AZURE_RESOURCE_GROUP --multicontainer-config-type compose --multicontainer-config-file deploy/production/docker-compose.yml
  when: manual
  environment:
    name: production
    url: https://$AZURE_APP_SERVICE_NAME.azurewebsites.net
  only:
    - /^development.*$/
    - /^deployment.*$/

关键修改说明 #

1. 合并Build与Push阶段：把两个阶段合并为一个Job，避免跨Runner环境传递镜像的问题（每个GitLab CI Job运行在独立容器，前一个Job的镜像不会保留）
2. 添加ACR完整前缀：所有镜像命名都带上$ACR_LOGIN_SERVER，确保符合ACR的仓库命名规则，推送时能正确匹配
3. 修正Docker Compose镜像引用：用sed命令在部署阶段替换配置文件中的镜像地址，确保指向ACR中的镜像
4. 简化流水线结构：减少不必要的阶段划分，提升运行效率

额外检查项 #

• 确认ACR_LOGIN_SERVER变量格式正确（例如：xxx.azurecr.io）
• 确保ACR允许自动创建仓库（默认开启），或者手动提前创建webapi、client、gateway三个仓库
• 验证Azure服务主体拥有ACR的推送权限和App Service的部署权限

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