Text of docs.docker.com › build › ci › github-actions › github-builder-architecture as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Docker GitHub Builder architecture | Docker Docs

Skip to content Search or ask Docker Search documentation Ask Docker Start a new chat Answers are generated based on the documentation. On this page: Docker Build Docker GitHub Builder separates repository orchestration from build implementation. A consuming repository decides when a build runs, which permissions and secrets are granted, and which inputs are passed. The reusable workflow in docker/github-builder repository owns the build implementation itself.

That split keeps repository workflows short while centralizing BuildKit, caching, provenance, SBOM generation, signing, and multi-platform assembly in one Docker-maintained path. Core architecture A caller workflow invokes either build.yml or bake.yml . build.yml is the entrypoint for Dockerfile-oriented builds. bake.yml is the entrypoint for Bake-oriented builds, where the Bake definition remains the source of truth for targets and overrides.

In both cases the caller still owns repository policy, including triggers, branch conditions, permissions, secrets, target selection, metadata inputs, and the choice between image output and local output. The registry-identities input supplies non-secret configuration for keyless registry authentication. A separate job validates this configuration. Jobs that need registry access authenticate with the configured provider.

You can combine identities with credentials passed through the registry-auths secret. See Registry identities for supported providers and configuration. Inside the reusable workflow, the first phase prepares the build. It validates the incoming inputs, resolves the runner config, and expands a multi-platform request into one job per platform. The execution model is easiest to picture as a matrix where linux/amd64 runs on ubuntu-24.04 and linux/arm64 runs on ubuntu-24.04-arm .

Each platform job builds independently, then the workflow finalizes the result into one caller-facing output contract. requested platforms : linux/amd64,linux/arm64 conceptual platform jobs : linux/amd64 -> ubuntu-24.04 linux/arm64 -> ubuntu-24.04-arm Runner selection The runner input accepts either a single GitHub-hosted Linux runner label or a newline-delimited platform mapping. For the default mapping, see Runner mapping .

In the platform job, the runner label resolves to a single value: runner : ubuntu-24.04 A mapping must define a default runner. Other keys are platform prefixes, and the most specific matching prefix wins. For example, linux/arm matches variants such as linux/arm/v7 , while linux/arm64 is a separate prefix: In the following example, linux matches Linux platforms that do not match a longer prefix. The default key is still required because it is the fallback when no platform prefix matches. runner : | default=ubuntu-24.04 linux=ubuntu-24.04 linux/arm=ubuntu-24.04-arm linux/arm64=ubuntu-24.04-arm The reusable workflows require GitHub-hosted Linux runners.

The legacy auto , amd64 , and arm64 values are still accepted for compatibility, but emit deprecation warnings. Use an explicit runner label or platform mapping instead. Execution path The execution path stays short on purpose. The consuming repository calls the reusable workflow. The reusable workflow prepares the build, runs the per-platform jobs, and finalizes the result. For image output, finalization produces a registry image and multi-platform manifest.

For local output, finalization merges the per-platform files and can upload the merged result as a GitHub artifact. The caller does not need to reconstruct how Buildx, BuildKit, caching, or manifest assembly were wired together. The two reusable entrypoints build.yml is the better fit when the build is already expressed as a Dockerfile-oriented workflow. It lines up naturally with concepts such as context , file , target , build-args , labels , annotations , and platforms .

This is the entrypoint that feels closest to docker/build-push-action , except the workflow implementation is centralized. bake.yml is the better fit when the repository already uses Bake as the build definition. It preserves the Bake model, including target resolution, files , set , and vars , while still routing execution through the same Docker-maintained build path. One important architectural detail is that the Bake workflow is centered on one target per workflow call, which keeps provenance, digest handling, and final manifest assembly scoped to one build unit at a time.

Output model The reusable workflows expose a stable set of caller-facing outputs so downstream jobs can consume results without understanding the internal job graph. In practice, the main values are digest , meta-json , artifact-name , output-type , and signed . That contract matters because it keeps promotion, publishing, or follow-on automation decoupled from the mechanics of runner selection and per-platform assembly.

Examples Dockerfile-oriented image build The following example shows the shape of a multi-platform image build driven by build.yml . name : ci on : push : branches : - "main" tags : - "v*" pull_request : permissions : contents : read jobs : build : uses : docker/github-builder/.github/workflows/build.yml@v1 permissions : contents : read id-token : write with : output : image push : ${{ github.event_name != 'pull_request' }} platforms : linux/amd64,linux/arm64 meta-images : name/app meta-tags : | type=ref,event=branch type=ref,event=pr type=semver,pattern={{version}} secrets : registry-auths : | - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} This call is small because the reusable workflow absorbs the heavy lifting.

The repository decides when the build should run and which inputs it wants, while the shared implementation handles Buildx setup, BuildKit configuration, platform fan-out, metadata generation, provenance, SBOM generation, signing, and final manifest creation. Bake-oriented local output The following example shows the shape of a Bake call that exports local output and uploads the merged artifact. name : ci on : pull_request : permissions : contents : read jobs : bake : uses : docker/github-builder/.github/workflows/bake.yml@v1 permissions : contents : read id-token : write with : output : local target : binaries artifact-upload : true artifact-name : bake-output This form is useful when the repository already keeps its build definition in Bake and wants to preserve that source of truth.

The workflow injects the local output behavior into the Bake run, executes the target per platform when needed, and merges the result into one caller-facing artifact. Why this architecture works Performance The performance story comes from native platform fan-out, shared BuildKit configuration, and centralized cache handling. Multi-platform work can be spread across matching GitHub-hosted runners instead of forcing every architecture through one build machine.

That reduces emulation pressure, shortens the critical path for cross-platform builds, and gives every consuming repository the same optimized build baseline. Security The security model comes from putting the build implementation in Docker-maintained reusable workflows instead of ad hoc job steps in each consumer repository. The caller still controls permissions and secrets, but the build logic itself is centrally reviewed and versioned.

The project also treats provenance, SBOM generation, and signing as first-class concerns, which strengthens the trust boundary between repository orchestration and artifact production. When caching is enabled and GitHub OIDC is available through id-token: write , BuildKit signs exported cache entries with Cosign. Before importing cache, it checks signatures against the expected workflow identity and source repository policy.

Cache signing is separate from the sign input that controls output signing. See Signed GitHub Actions cache . The optional buildkit-proxy-network input routes network access from Dockerfile RUN instructions through BuildKi

The rest of this page is on the live site.