Github Action构建Docker镜像时标签格式无效问题排查与修复

问题重现 #

在GitHub Action中配置Docker镜像构建流程，尝试使用Git标签a0.15.3作为镜像标签，通过docker/metadata-action提取元数据时触发错误：

ERROR: invalid tag "/:a0.15.3": invalid reference format

错误原因 #

1. 前缀"/:"的来源：该前缀是因为未在docker/metadata-action中指定有效的镜像仓库名称。当images参数缺失或为空时，action生成标签时会尝试拼接空仓库名+冒号+标签值，最终形成/:a0.15.3这种非法格式。
2. 是否导致错误：是的，Docker镜像引用必须符合[仓库名/][镜像名]:[标签]的格式，空仓库名导致的/:a0.15.3完全不符合规范，直接触发格式校验失败。

修复方案 #

1. 正确配置docker/metadata-action的images参数 #

在Workflow中给docker/metadata-action指定你的镜像仓库和镜像名，示例如下：

- name: 生成Docker元数据
  uses: docker/metadata-action@v5
  id: meta
  with:
    # 替换为你的镜像仓库地址，比如Docker Hub或GHCR
    images: your-docker-username/your-image-repo
    # 配置标签规则，提取Git标签作为镜像标签
    tags: |
      type=ref,event=tag

• 如果使用GitHub容器注册表（GHCR），images值应为ghcr.io/your-github-username/your-image-repo

2. 在构建步骤中使用正确的标签输出 #

确保后续的docker/build-push-action步骤引用metadata-action生成的标签：

- name: 构建并推送Docker镜像
  uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: ${{ steps.meta.outputs.tags }}

额外检查 #

• 确认Git标签a0.15.3本身无特殊字符（Docker标签仅允许小写字母、数字、_、.、-），当前标签格式是合法的
• 确保Workflow拥有推送目标镜像仓库的权限

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