GitHub Actions构建多平台Docker镜像推GHCR成功，拉取时提示无匹配Manifest

通过GitHub Actions构建多平台Docker镜像，工作流执行成功，但从GHCR拉取镜像时出现错误：

no matching manifest for linux/amd64 in the manifest list entries

暂未在ARM架构系统上尝试拉取。使用的Workflow文件如下：

name: Build and push image

on:
  push:
    tags: ["*"]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build_and_push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      attestations: write
      id-token: write
    strategy:
      matrix:
        platform:
          - linux/amd64
          - linux/arm/v6
          - linux/arm/v7
          - linux/arm64
          - linux/ppc64le
          - linux/riscv64
          - linux/s390x
    steps:
      - uses: actions/checkout@v4

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@v6
        with:
          push: true
          platforms: ${{ matrix.platform }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

      - name: Generate artifact attestation
        uses: actions/attest-build-provenance@v2
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

原因分析 #

当前Workflow使用matrix为每个平台单独构建并推送镜像，这会生成多个独立的单架构镜像，而非包含所有平台的Manifest List（多架构镜像索引）。当你尝试拉取镜像时，Docker默认会请求Manifest List，但仓库中并没有这个索引文件，因此出现匹配失败的错误。

解决方法 #

修改Workflow，移除matrix配置，在docker/build-push-action中一次性指定所有目标平台，让Buildx构建并推送统一的Manifest List，同时确保所有架构镜像关联到同一个标签。

修改后的Workflow文件：

name: Build and push image

on:
  push:
    tags: ["*"]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build_and_push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      attestations: write
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push multi-platform Docker image
        id: push
        uses: docker/build-push-action@v6
        with:
          push: true
          # 一次性指定所有目标平台
          platforms: |
            linux/amd64
            linux/arm/v6
            linux/arm/v7
            linux/arm64
            linux/ppc64le
            linux/riscv64
            linux/s390x
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          # 启用Manifest List推送（默认已开启，显式声明更清晰）
          manifest: true

      - name: Generate artifact attestation for manifest list
        uses: actions/attest-build-provenance@v2
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

关键修改点 #

• 移除strategy.matrix配置，不再为每个平台单独执行任务
• 在docker/build-push-action的platforms参数中一次性列出所有目标平台
• 显式声明manifest: true（默认已启用，用于明确表明要推送Manifest List）

验证方法 #

修改后重新触发Workflow，推送完成后，使用以下命令查看镜像的Manifest List：

docker buildx imagetools inspect ghcr.io/[你的用户名]/[镜像名]:[标签]

如果输出包含所有指定平台的信息，说明构建成功，此时再拉取镜像就不会出现匹配错误。

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