How to Build a Multi-Arch Docker Image in GitLab CI

Run Buildx inside the dind service to build and push a multi-platform image to the GitLab registry.

Use docker:dind, register QEMU emulators, create a Buildx builder, then docker buildx build --platform ... --push. The job token logs in to the project registry.

Buildx in dind

Install emulators, create a builder, then build both platforms and push in one command.

build-multiarch:
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - docker run --privileged --rm tonistiigi/binfmt --install all
    - docker buildx create --use
    - docker buildx build
      --platform linux/amd64,linux/arm64
      -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
      --push .

Gotchas

• Registering QEMU (binfmt --install all) needs a privileged dind service, so the runner must allow privileged mode.
• Buildx pushes the multi-platform manifest directly; you cannot --load a multi-arch image into the local daemon.
• Match the docker client image version to the docker:dind service version or the build aborts.

Related guides