Skip to content

Distributed builds #2

Description

@crazy-max

Currently users rely on a complex workflow to distribute builds across runners: https://docs.docker.com/build/ci/github-actions/multi-platform/#distribute-build-across-multiple-runners

For example with build-push-action:

name: ci

on:
  push:

env:
  REGISTRY_IMAGE: user/app

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform:
          - linux/amd64
          - linux/arm64
    steps:
      - name: Prepare
        run: |
          platform=${{ matrix.platform }}
          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY_IMAGE }}

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - 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 by digest
        id: build
        uses: docker/build-push-action@v6
        with:
          platforms: ${{ matrix.platform }}
          labels: ${{ steps.meta.outputs.labels }}
          tags: ${{ env.REGISTRY_IMAGE }}
          outputs: type=image,push-by-digest=true,name-canonical=true,push=true

      - name: Export digest
        run: |
          mkdir -p ${{ runner.temp }}/digests
          digest="${{ steps.build.outputs.digest }}"
          touch "${{ runner.temp }}/digests/${digest#sha256:}"

      - name: Upload digest
        uses: actions/upload-artifact@v4
        with:
          name: digests-${{ env.PLATFORM_PAIR }}
          path: ${{ runner.temp }}/digests/*
          if-no-files-found: error
          retention-days: 1

  merge:
    runs-on: ubuntu-latest
    needs:
      - build
    steps:
      - name: Download digests
        uses: actions/download-artifact@v4
        with:
          path: ${{ runner.temp }}/digests
          pattern: digests-*
          merge-multiple: true

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY_IMAGE }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Create manifest list and push
        working-directory: ${{ runner.temp }}/digests
        run: |
          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
            $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *)

      - name: Inspect image
        run: |
          docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }}

It often leads to confusion with already complex workflows which a reusable workflow could solve.

Activity

  1. added theissue type on Jul 24, 2025
  2. crazy-max commented on Jul 29, 2025

    @crazy-max
    MemberAuthor

    We started to enhance distributed builds in build-push-action and bake-action using reusable workflows some time ago:

    It would be straightforward to use and would avoid GitHub artifacts to export digests: https://deploy-preview-22163--docsdocker.netlify.app/build/ci/github-actions/multi-platform/#distribute-multi-platform-build-across-runners

    We didn't release these reusable workflows yet because we wanted secure reusable workflows first.

  3. crazy-max commented on Jul 29, 2025

    @crazy-max
    MemberAuthor

    Atm we need to use the Path context as there is an issue to keep fetch tags with Git context and Bake: docker/actions-toolkit#677 (comment)

    As Git context is a requirement for our reusable workflows we need moby/buildkit#5974 first.

  4. self-assigned this
    on Jul 29, 2025
  5. crazy-max commented on Aug 5, 2025

    @crazy-max
    MemberAuthor

    Related to docker/build-push-action#1022 we would need to manage annotations correctly. If user wants annotations on index then it should set them in buildx imagetools create in merge job, otherwise set them to each manifest. Would need specific logic for this I think.

  6. crazy-max commented on Aug 12, 2025

    @crazy-max
    MemberAuthor

    Related to docker/build-push-action#1022 we would need to manage annotations correctly. If user wants annotations on index then it should set them in buildx imagetools create in merge job, otherwise set them to each manifest. Would need specific logic for this I think.

    Similar to docker/metadata-action#534

  7. transferred this issue fromon Aug 18, 2025
  8. added theissue type on Aug 18, 2025
  9. changed the title [-]Reusable workflows distributed builds[/-] [+]Distributed builds[/+] on Aug 18, 2025
  10. removed theissue type on Aug 18, 2025
  11. crazy-max commented on Nov 14, 2025

    @crazy-max
    MemberAuthor

    Started to work on distributed builds across runners with bake in #22

  12. added theissue type on Aug 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions