GitHub Actions 多平台构建

适用场景

• •多平台镜像构建与发布（amd64/arm64）
• •需要 digest 合并 manifest list
• •需要 Buildx 缓存与标签管理

不适用

• •单平台构建且不合并 manifest
• •不推送到镜像仓库

核心检查清单

Build job (matrix)

• • Matrix 可用列表形式： platform: [linux/amd64, linux/arm64]（fail-fast: false）
• • 环境变量: REGISTRY_IMAGE (小写), VERSION
• • 生成 REGISTRY_IMAGE 时强制小写（如 tr '[:upper:]' '[:lower:]'）
• • actions/checkout@v4
• • docker/setup-buildx-action@v3
• • docker/login-action@v3 (ghcr.io)
• • docker/build-push-action@v6:
  • • outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true
  • • platforms: ${{ matrix.platform }}
  • • cache-from: type=gha, cache-to: type=gha,mode=max
• • 获取 digest: digest="${{ steps.build.outputs.digest }}"
• • 导出 digest: touch "/tmp/digests/${digest#sha256:}"
• • artifact 名避免 /（如 linux/amd64 → linux-amd64）
• • actions/upload-artifact@v4: name: digests-<safe-platform>

Merge job

• • needs: build, runs-on: ubuntu-latest
• • actions/download-artifact@v4: pattern: digests-*, merge-multiple: true
• • docker/setup-buildx-action@v3
• • (可选) docker/metadata-action@v5: 生成标签
• • docker/login-action@v3
• • 通过 metadata 输出或自定义标签传入 imagetools create
• • docker buildx imagetools create -t <tag> <image@sha256:digest>...

值得学习的点

• •✅ digest + manifest 分离式流程（build 推 digest，merge 合并）
• •✅ push-by-digest + name-canonical 防止 tag 冲突
• •✅ merge job 统一打标签，避免重复推送
• •✅ permissions 最小化（contents: read，packages: write）
• •✅ 短期 artifact（retention-days: 1）

常见错误

• •❌ 单 runner 构建所有平台 → ✅ 使用平台匹配的 runner
• •❌ 忘记 push-by-digest → ✅ 必须使用以安全合并
• •❌ GHCR 镜像名未小写 → ✅ 强制小写
• •❌ 跳过 digest artifact → ✅ 必须传递到 merge job

基线要求

• •✅ 不声称文件已创建除非实际创建
• •✅ 不跳过验证即使模板存在
• •✅ 输出检查清单而非完整模板（除非明确要求）
• •✅ 尊重个人/项目技能位置

快速自检（必做）

• • frontmatter 仅含 name 与 description
• • description 以 “Use when” 开头并包含触发词
• • 未声明任何未执行的操作或验证

借口-现实

红旗

• •“默认输出完整模板”
• •“未执行也声明已验证”