GitHub Actions中Docker推送至GCR生成多镜像的原因排查

出现多个镜像的核心原因是构建并推送的是多平台镜像（Manifest List），而非单平台镜像，具体拆解如下：

1. build-push-action的默认行为 #

你使用的docker/build-push-action@v3.3.0默认基于Docker Buildx运行，而GitHub Actions环境中的Buildx通常预配置了支持多平台构建的builder。如果工作流没有显式指定platforms参数，Buildx可能会默认构建当前runner平台及其他隐含平台的镜像，生成包含多个平台镜像的Manifest List——这个结构本质是一个指向各平台镜像的索引文件，而非单一镜像。

2. imagetools create的复制逻辑 #

执行docker buildx imagetools create时，它会完整复制源镜像的结构：如果源是Manifest List，目标GCR仓库会同时生成Manifest List和对应的每个平台的镜像文件，最终在GCR中显示为多个镜像条目（每个平台一个镜像+Manifest List本身）。

3. 本地registry的存储特性 #

你使用的registry:2完全支持存储Manifest List和多平台镜像，不会对其进行合并或转换，因此Manifest List会原封不动地被传递到后续步骤。

要生成单一镜像，只需在build-push-action步骤中显式指定单平台：

- name: build and push to local registry
  uses: docker/build-push-action@v3.3.0
  with:
    context: ${{ inputs.context }}
    file: ${{ inputs.context }}/${{ inputs.dockerfile }}
    no-cache: ${{ inputs.no_cache }}
    build-args: ${{ inputs.build_args }}
    push: true
    tags: ${{ env.LOCAL_IMAGE }}
    outputs: type=image,oci-mediatypes=false
    # 显式指定单平台，比如当前runner的x86_64平台
    platforms: linux/amd64

添加platforms参数后，Buildx只会构建指定平台的单一镜像，后续复制到GCR时也只会生成一个镜像条目。

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