docker/github-builder

• Overview
• Key Advantages
  • Performance
  • Security
  • Isolation & Reliability
• Usage
  • Build reusable workflow
    • Inputs
    • Secrets
    • Outputs
  • Bake reusable workflow
    • Inputs
    • Secrets
    • Outputs

Overview

This repository provides official Docker-maintained reusable GitHub Actions workflows
to securely build container images and artifacts using Docker best practices.
The reusable workflows incorporate functionality from our GitHub Actions like
docker/build-push-action,
docker/metadata-action, etc.,
into a single workflow:

name: ci

permissions:
  contents: read

on:
  push:
    branches:
      - 'main'
    tags:
      - 'v*'
  pull_request:

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      meta-images: name/app
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

This workflow provides a trusted BuildKit instance and generates signed
SLSA-compliant provenance attestations, guaranteeing the build happened from
the source commit and all build steps ran in isolated sandboxed environments
from immutable sources. This enables GitHub projects to follow a seamless path
toward higher levels of security and trust.

Key Advantages

Performance

• Native parallelization for multi-platform builds.
  Workflows can automatically distribute builds across runners based on target
  platform to be built, improving throughput for other architectures without
  requiring emulation or custom CI logic
  or self-managed runners.

• Optimized cache warming & reuse.
  The builder can use the GitHub Actions cache backend to persist layers across
  branches, PRs, and rebuilds. This significantly reduces cold-start times and
  avoids repeating expensive dependency installations, even for external
  contributors' pull requests.

• Centralized build configuration.
  Repositories no longer need to configure buildx drivers, tune storage, or
  adjust resource limits. The reusable workflows encapsulate the recommended
  configuration, providing fast, consistent builds across any project that
  opts in.

Security

• Trusted workflows in the Docker organization.
  Builds are executed by reusable workflows defined in the @docker
  organization, not by arbitrary user-defined workflow steps. Consumers can
  rely on GitHub's trust model and repository protections on the Docker side
  (branch protection, code review, signing, etc.) to reason about who controls
  the build logic.

• Verifiable, immutable sources.
  The workflows use the GitHub OIDC token and the exact commit SHA to obtain
  source and to bind it into SLSA provenance. This ensures that the build is
  tied to the repository contents as checked in—no additional CI step can
  silently swap out what is being built.

• Signed SLSA provenance for every build.
  BuildKit generates SLSA-compliant provenance attestation
  artifacts that are signed with an identity bound to the GitHub workflow.
  Downstream consumers can verify:

  • which builder commit produced the image
  • which source code commit produced the image
  • which workflow and job executed the build
  • what inputs and build parameters were used

• Protection from user workflow tampering.
  The build steps are pre-defined and optimized in the reusable workflow, and
  cannot be altered by user configuration. This protects against tampering:
  preventing untrusted workflow steps from modifying build logic, injecting
  unexpected flags, or producing misleading provenance.

Isolation & Reliability

• Separation between user CI logic and build logic.
  The user's workflow orchestrates when to build but not how to build.
  The actual build steps live in the Docker-maintained reusable workflows,
  which cannot be modified from the consuming repository.

• Immutable, reproducible build pipeline.
  Builds are driven by declarative inputs (repository commit, build
  configuration, workflow version). This leads to:

  • reproducibility (same workflow + same inputs → same outputs)
  • auditability (inputs and workflow identity recorded in provenance)
  • reliability (less dependence on ad-hoc per-repo CI scripting)

• Reduced CI variability and config drift.
  By reusing the same workflows, projects avoid maintaining custom build logic
  per repository. Caching, provenance, SBOM generation, and build settings
  behave uniformly across all adopters.

• Higher assurance for downstream consumers.
  Because artifacts are produced by a workflow in the @docker
  organization, with SLSA provenance attached, consumers can verify both the
  source commit and the builder identity before trusting or promoting an
  image, an essential part of supply-chain hardening.

Usage

Build reusable workflow

The build.yml reusable workflow lets you build
container images and artifacts from a Dockerfile with a user experience similar
to docker/build-push-action.
It provides a Docker-maintained, opinionated build pipeline that applies best
practices for security, performance, and reliability by default, including
isolated execution and signed SLSA provenance while keeping per-repository
configuration minimal.

name: ci

permissions:
  contents: read

on:
  push:
    branches:
      - 'main'
    tags:
      - 'v*'
  pull_request:

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    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 }}

  # Optional job to verify the pushed images' signatures. This is already done
  # in the `build` job and can be omitted. It's provided here as an example of
  # how to use the `verify.yml` reusable workflow.
  build-verify:
    uses: docker/github-builder/.github/workflows/verify.yml@v1
    if: ${{ github.event_name != 'pull_request' }}
    needs:
      - build
    with:
      builder-outputs: ${{ toJSON(needs.build.outputs) }}
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

Inputs

cache-from: |
  user/app:cache
  type=local,src=path/to/dir

tags: name/app:latest,name/app:1.0.0

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    with:
      output: image
      build-args: |
        VERSION={{meta.version}}
      meta-images: name/app

Secrets

Outputs

These outputs are available as needs.<job_id>.outputs.* and can be passed
directly to the verify.yml reusable workflow
with builder-outputs: ${{ toJSON(needs.<job_id>.outputs) }}.

Bake reusable workflow

The bake.yml reusable workflow lets you build
container images and artifacts from a Bake definition
with a user experience similar to docker/bake-action.
It provides a Docker-maintained, opinionated build pipeline that applies best
practices for security, performance, and reliability by default, including
isolated execution and signed SLSA provenance while keeping per-repository
configuration minimal.

name: ci

permissions:
  contents: read

on:
  push:
    branches:
      - 'main'
    tags:
      - 'v*'
  pull_request:

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      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 }}

  # Optional job to verify the pushed images' signatures. This is already done
  # in the `bake` job and can be omitted. It's provided here as an example of
  # how to use the `verify.yml` reusable workflow.
  bake-verify:
    uses: docker/github-builder/.github/workflows/verify.yml@v1
    if: ${{ github.event_name != 'pull_request' }}
    needs:
      - bake
    with:
      builder-outputs: ${{ toJSON(needs.bake.outputs) }}
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

Inputs

List type is a newline-delimited string

set: target.args.mybuildarg=value

set: |
  target.args.mybuildarg=value
  foo*.args.mybuildarg=value

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    with:
      output: image
      set: |
        *.args.VERSION={{meta.version}}
      meta-images: name/app

Secrets

Outputs

These outputs are available as needs.<job_id>.outputs.* and can be passed
directly to the verify.yml reusable workflow
with builder-outputs: ${{ toJSON(needs.<job_id>.outputs) }}.