GitHub Actions构建Docker镜像标签格式无效问题排查

问题场景 #

在使用GitHub Actions构建并推送Docker镜像时，遇到标签格式错误：

invalid tag "gcr.io/af-image/docker-image-test:refs/heads/master": invalid reference format

相关Build and Push步骤配置：

- name: Build and push
  id: docker_build
  uses: docker/build-push-action@v3
  with:
    context: .
    file: ./Dockerfile
    push: ${{ github.event_name != 'pull_request' }}
    tags: gcr.io/af-image/docker-image-test:refs/heads/master

标签生成脚本：

- name: Prepare docker tag
  id: prep
  run: |
    set -x
    VERSION=${GITHUB_REF#refs/tags/}
    TAG=gcr.io/af-image/${{ env.SERVICE_NAME }}:${VERSION#"${{ env.SERVICE_NAME }}-"}
    echo ::set-output name=tag::${TAG}

问题根源 #

当前分支未打标签时，${GITHUB_REF#refs/tags/}的截取逻辑会保留完整的分支引用路径refs/heads/master，而Docker镜像标签不允许包含/字符，且只能由小写字母、数字、.、_、-组成，最终生成的标签不符合格式要求。

解决方案 #

修改标签生成脚本，区分标签和分支两种场景，分别生成合法的Docker标签：

- name: Prepare docker tag
  id: prep
  run: |
    set -x
    if [[ $GITHUB_REF == refs/tags/* ]]; then
      # 标签场景：截取标签名并移除前缀（如果有）
      VERSION=${GITHUB_REF#refs/tags/}
      VERSION=${VERSION#"${{ env.SERVICE_NAME }}-"}
    else
      # 分支场景：截取分支名并替换/为-，避免格式错误
      BRANCH_NAME=${GITHUB_REF#refs/heads/}
      VERSION=${BRANCH_NAME//\//-}
    fi
    # 使用GitHub Actions最新语法设置输出变量
    TAG=gcr.io/af-image/${{ env.SERVICE_NAME }}:$VERSION
    echo "tag=$TAG" >> $GITHUB_OUTPUT

关键优化点 #

1. 分支名处理：将分支名中的/替换为-，比如feature/test会转为feature-test，符合Docker标签规范
2. 语法更新：替换旧的::set-output语法为$GITHUB_OUTPUT，适配GitHub Actions的最新版本要求
3. 场景区分：通过判断GITHUB_REF的前缀，分别处理标签和分支的标签生成逻辑，覆盖所有触发场景

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