How to Build a Multi-Arch Docker Image in GitHub Actions

QEMU plus Buildx builds one image manifest covering several CPU architectures in a single step.

Set up QEMU and Buildx, then pass platforms: linux/amd64,linux/arm64 to docker/build-push-action to emit a multi-arch manifest.

Steps

• Set up QEMU for cross-architecture emulation.
• Set up Docker Buildx.
• Run build-push-action with a platforms: list.

Workflow

jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v6
        with:
          push: true
          platforms: linux/amd64,linux/arm64
          tags: ghcr.io/${{ github.repository }}:latest

Gotchas

• Emulated arm64 builds are slower; cache layers to offset the cost.
• Latchkey offers native arm64 runners so multi-arch builds run cheaper without QEMU overhead.

Related guides