From a4b5b06e1d4f42394d8af8398cbce0a36c308fe8 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 30 Oct 2026 11:19:49 +0000
Subject: [PATCH 1/7] docs: lead GitHub Actions recipes with Docker GitHub
Builder
GitHub Actions examples lead with individual actions despite the reusable build workflows. Present Builder first for supported recipes, explain its defaults, and retain action-based alternatives for tasks that need them.
---
.../manuals/build/ci/github-actions/_index.md | 158 ++++++++------
.../build/ci/github-actions/annotations.md | 42 +++-
.../build/ci/github-actions/attestations.md | 43 +++-
.../manuals/build/ci/github-actions/cache.md | 156 +++++++++-----
.../github-actions/github-builder/_index.md | 104 +++++-----
.../ci/github-actions/github-builder/bake.md | 4 +-
.../ci/github-actions/manage-tags-labels.md | 58 ++++++
.../build/ci/github-actions/multi-platform.md | 194 ++++++------------
.../github-actions/push-multi-registries.md | 46 +++++
.../ci/github-actions/reproducible-builds.md | 37 +++-
.../build/ci/github-actions/secrets.md | 38 +++-
11 files changed, 576 insertions(+), 304 deletions(-)
diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md
index 50712cb99dec..c0c3215f5fe3 100644
--- a/content/manuals/build/ci/github-actions/_index.md
+++ b/content/manuals/build/ci/github-actions/_index.md
@@ -1,7 +1,7 @@
---
title: Docker Build GitHub Actions
linkTitle: GitHub Actions
-description: Docker maintains a set of official GitHub Actions for building Docker images.
+description: Build and publish images with Docker GitHub Builder or individual Docker GitHub Actions.
keywords: ci, github actions, gha, build, introduction, tutorial
aliases:
- /guides/gha/
@@ -9,42 +9,12 @@ aliases:
- /build/ci/github-actions/examples/
---
-GitHub Actions is a popular CI/CD platform for automating your build, test, and
-deployment pipeline. Docker provides a set of official GitHub Actions for you to
-use in your workflows. These official actions are reusable, easy-to-use
-components for building, annotating, and pushing images.
-
-The following GitHub Actions are available:
-
-- [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images):
- build and push Docker images with BuildKit.
-- [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake):
- enables using high-level builds with [Bake](../../bake/_index.md).
-- [Docker Login](https://github.com/marketplace/actions/docker-login):
- sign in to a Docker registry.
-- [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx):
- creates and boots a BuildKit builder.
-- [Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action):
- extracts metadata from Git reference and GitHub events to generate tags,
- labels, and annotations.
-- [Docker Setup Compose](https://github.com/marketplace/actions/docker-setup-compose):
- installs and sets up [Compose](../../../compose).
-- [Docker Setup Docker](https://github.com/marketplace/actions/docker-setup-docker):
- installs Docker Engine.
-- [Docker Setup QEMU](https://github.com/marketplace/actions/docker-setup-qemu):
- installs [QEMU](https://github.com/qemu/qemu) static binaries for
- multi-platform builds.
-- [Docker Scout](https://github.com/docker/scout-action):
- analyze Docker images for security vulnerabilities.
-
-Using Docker's actions provides an easy-to-use interface, while still allowing
-flexibility for customizing build parameters.
-
-> [!NOTE]
-> For an alternative to configuring individual actions, see
-> [Docker GitHub Builder](/manuals/build/ci/github-actions/github-builder/_index.md).
-> It provides Docker-maintained reusable workflows for building images and artifacts
-> with BuildKit.
+GitHub Actions automates your build, test, and deployment pipeline. Use
+[Docker GitHub Builder](github-builder/_index.md) to build and publish images
+with Docker-maintained reusable workflows. Builder manages Buildx setup,
+platform distribution, metadata, and signing. Start with Builder for supported
+build tasks, and compose individual actions when you need custom job steps or
+controls outside the reusable workflow interface.
## Get started
@@ -75,6 +45,69 @@ Create `.github/workflows/docker-ci.yml` in your repository with the following
contents. Replace `my-image` with the name of your Docker Hub repository, and
change `main` if your default branch has a different name.
+```yaml
+name: ci
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ push: ${{ github.event_name != 'pull_request' }}
+ set-meta-labels: true
+ set-meta-annotations: true
+ meta-images: ${{ vars.DOCKERHUB_USERNAME }}/my-image
+ secrets:
+ registry-auths: |
+ - registry: docker.io
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+```
+
+Call the reusable workflow with `uses` at the job level, rather than inside
+`steps`. Grant `contents: read` to fetch the repository and `id-token: write`
+for signing with GitHub's OpenID Connect token. With the default `sign: auto`,
+Builder signs attestation manifests when pushing an image. See the
+[Build workflow](github-builder/build.md) for inputs and outputs.
+
+Commit the workflow file and push it to your default branch to run it. The
+workflow also runs on pull requests. With `push: false`, the default
+`registry-login: auto` skips registry login and `sign: auto` skips signing.
+Pull requests from forks can build without Docker Hub secrets or a writable
+OpenID Connect token. Builds that need private dependencies still need access
+to those dependencies.
+
+Builder checks out the repository for the triggering event in its own jobs.
+Files changed in a caller job aren't automatically available to the build.
+
+Builder uses the metadata action to generate tags from the GitHub event.
+For example, a push to `main` publishes `DOCKERHUB_USERNAME/my-image:main`.
+The `set-meta-labels` and `set-meta-annotations` switches also apply generated
+labels and annotations; both are disabled by default. See
+[Manage tags and labels](manage-tags-labels.md) and [Annotations](annotations.md)
+to customize this metadata.
+
+This workflow builds images but doesn't run application tests. To add tests,
+see [Test before push](test-before-push.md). For additional build options, see
+[Multi-platform images](multi-platform.md) and
+[SBOM and provenance attestations](attestations.md).
+
+## Build with individual actions
+
+Use individual actions to load images into a job's Docker image store, run
+steps before or after a build on the same runner, or configure the builder
+directly. The following alternative uses the same credentials, triggers, and
+metadata as the Builder example:
+
```yaml
name: Build and push Docker image
@@ -116,30 +149,35 @@ jobs:
annotations: ${{ steps.meta.outputs.annotations }}
```
-Commit the workflow file and push it to your default branch to run it. The
-workflow also runs on pull requests. Pull-request builds skip signing in to
-Docker Hub and pushing the image, so they don't require registry secrets,
-including for pull requests from forks.
-
-The build action uses Git context by default: BuildKit fetches your repository
-directly at the Git reference for the event that triggered the workflow, so no
-checkout step is needed. Changes to files made by earlier workflow steps are
-ignored because the build uses files from Git.
-
-The metadata action generates tags, labels, and
-annotations from the GitHub event and passes them to the build step. For
-example, a push to `main` publishes `DOCKERHUB_USERNAME/my-image:main`.
-See [Manage tags and labels](/manuals/build/ci/github-actions/manage-tags-labels.md)
-and [Annotations](/manuals/build/ci/github-actions/annotations.md) to customize
-this metadata.
+The build action uses Git context by default: BuildKit fetches the repository
+at the triggering Git reference. No checkout step is needed, and changes made
+by earlier steps aren't included. Use a checkout and a path context when the
+build needs files changed by earlier steps.
-This workflow builds images but doesn't run application tests. To add tests,
-see [Test before push](/manuals/build/ci/github-actions/test-before-push.md).
-For additional build options, see
-[Multi-platform images](/manuals/build/ci/github-actions/multi-platform.md) and
-[SBOM and provenance attestations](/manuals/build/ci/github-actions/attestations.md),
-which covers default provenance and how to add SBOM attestations when pushing
-to a registry.
+### Available actions
+
+The following GitHub Actions are available:
+
+- [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images):
+ build and push Docker images with BuildKit.
+- [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake):
+ enables using high-level builds with [Bake](../../bake/_index.md).
+- [Docker Login](https://github.com/marketplace/actions/docker-login):
+ sign in to a Docker registry.
+- [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx):
+ creates and boots a BuildKit builder.
+- [Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action):
+ extracts metadata from Git reference and GitHub events to generate tags,
+ labels, and annotations.
+- [Docker Setup Compose](https://github.com/marketplace/actions/docker-setup-compose):
+ installs and sets up [Compose](../../../compose).
+- [Docker Setup Docker](https://github.com/marketplace/actions/docker-setup-docker):
+ installs Docker Engine.
+- [Docker Setup QEMU](https://github.com/marketplace/actions/docker-setup-qemu):
+ installs [QEMU](https://github.com/qemu/qemu) static binaries for
+ multi-platform builds.
+- [Docker Scout](https://github.com/docker/scout-action):
+ analyze Docker images for security vulnerabilities.
## Examples
diff --git a/content/manuals/build/ci/github-actions/annotations.md b/content/manuals/build/ci/github-actions/annotations.md
index 6faee4ab38d6..c5527a15107b 100644
--- a/content/manuals/build/ci/github-actions/annotations.md
+++ b/content/manuals/build/ci/github-actions/annotations.md
@@ -8,6 +8,41 @@ keywords: ci, github actions, gha, buildkit, buildx, annotations, oci
Annotations let you specify arbitrary metadata for OCI image components, such
as manifests, indexes, and descriptors.
+## Add annotations with Builder
+
+Use [Docker GitHub Builder](github-builder/build.md) with
+`set-meta-annotations: true` to apply annotations generated by the metadata
+action. The `annotations` input also accepts explicit annotations. This
+example adds a description to the final image index:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ push: true
+ set-meta-annotations: true
+ annotations: |
+ index:org.opencontainers.image.description=My application
+ meta-images: user/app
+ secrets:
+ registry-auths: |
+ - registry: docker.io
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+```
+
+## Add annotations with individual actions
+
To add annotations when building images with GitHub Actions, use the
[metadata-action] to automatically create OCI-compliant annotations. The
metadata action creates an `annotations` output that you can reference, both
@@ -77,7 +112,7 @@ jobs:
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
+
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
@@ -102,7 +137,8 @@ jobs:
## Configure annotation level
-By default, annotations are placed on image manifests. To configure the
+With individual actions, annotations are placed on image manifests by default.
+To configure the
[annotation level](../../metadata/annotations.md#specify-annotation-level), set
the `DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable on the
`metadata-action` step to a comma-separated list of all the levels that you
@@ -130,7 +166,7 @@ jobs:
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
+
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
diff --git a/content/manuals/build/ci/github-actions/attestations.md b/content/manuals/build/ci/github-actions/attestations.md
index 75a1c822b72e..e81206a2a06e 100644
--- a/content/manuals/build/ci/github-actions/attestations.md
+++ b/content/manuals/build/ci/github-actions/attestations.md
@@ -9,6 +9,47 @@ Software Bill of Material (SBOM) and provenance
[attestations](../../metadata/attestations/_index.md) add metadata about the contents of
your image, and how it was built.
+## Add attestations with Builder
+
+[Docker GitHub Builder](github-builder/build.md) manages provenance and signing
+in the reusable workflow. It uses max-level provenance for public repositories
+and min-level provenance for private repositories. These levels aren't caller
+inputs. Use individual actions below if you need to override the provenance
+level for a private repository.
+
+Set `sbom: true` to add an SBOM. With the default `sign: auto`, Builder signs
+attestation manifests when pushing an image, using the job's `id-token: write`
+permission:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ push: true
+ sbom: true
+ meta-images: user/app
+ secrets:
+ registry-auths: |
+ - registry: docker.io
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+```
+
+Use [build secrets](secrets.md) for credentials. Build argument values can
+appear in provenance, so don't pass secrets as build arguments.
+
+## Use individual actions
+
Attestations are supported with version 4 and later of the
`docker/build-push-action`.
@@ -67,7 +108,7 @@ jobs:
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
+
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
diff --git a/content/manuals/build/ci/github-actions/cache.md b/content/manuals/build/ci/github-actions/cache.md
index 4b30d2d175cc..0bc1530cbf8f 100644
--- a/content/manuals/build/ci/github-actions/cache.md
+++ b/content/manuals/build/ci/github-actions/cache.md
@@ -5,53 +5,24 @@ linkTitle: Cache management
keywords: ci, github actions, gha, buildkit, buildx, cache
---
-This page contains examples on using the cache storage backends with GitHub
-Actions.
+Use Docker GitHub Builder with the GitHub Actions cache backend for reusable
+build workflows. The individual-action examples cover other cache backends
+and cache mounts.
> [!NOTE]
>
> See [Cache storage backends](../../cache/backends/_index.md) for more
> details about cache storage backends.
-## Inline cache
-
-In most cases you want to use the [inline cache exporter](../../cache/backends/inline.md).
-However, note that the `inline` cache exporter only supports `min` cache mode.
-To use `max` cache mode, push the image and the cache separately using the
-registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
-
-```yaml
-name: ci
-
-on:
- push:
-
-jobs:
- docker:
- runs-on: ubuntu-latest
- steps:
- - name: Login to Docker Hub
- uses: docker/login-action@{{% param "login_action_version" %}}
- with:
- username: ${{ vars.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-
- - name: Set up Docker Buildx
- uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
-
- - name: Build and push
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: true
- tags: user/app:latest
- cache-from: type=registry,ref=user/app:latest
- cache-to: type=inline
-```
+## GitHub cache
-## Registry cache
+### Enable cache with Builder
-You can import/export cache from a cache manifest or (special) image
-configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md).
+[Docker GitHub Builder](github-builder/build.md) disables caching by default.
+Set `cache: true` to import and export GitHub Actions cache. Set
+`cache-mode: max` to export intermediate layers, and use `cache-scope` to
+separate builds for different images. Builder adds the platform to the scope
+for distributed builds and makes cache export failures non-fatal.
```yaml
name: ci
@@ -60,31 +31,34 @@ on:
push:
jobs:
- docker:
- runs-on: ubuntu-latest
- steps:
- - name: Login to Docker Hub
- uses: docker/login-action@{{% param "login_action_version" %}}
- with:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ push: true
+ cache: true
+ cache-mode: max
+ cache-scope: app
+ meta-images: user/app
+ secrets:
+ registry-auths: |
+ - registry: docker.io
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
- - name: Set up Docker Buildx
- uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
-
- - name: Build and push
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: true
- tags: user/app:latest
- cache-from: type=registry,ref=user/app:buildcache
- cache-to: type=registry,ref=user/app:buildcache,mode=max
```
-## GitHub cache
+The same cache inputs are available with the [Bake workflow](github-builder/bake.md).
+See [cache write restrictions](#cache-write-restrictions) for event restrictions.
+Builder's `cache-mode` input selects the layers to export (`min` or `max`);
+it doesn't grant cache write access.
### Cache backend API
+The following examples configure the backend with individual actions.
+
{{< summary-bar feature_name="Cache backend API" >}}
The [GitHub Actions cache exporter](../../cache/backends/gha.md)
@@ -355,3 +329,71 @@ jobs:
cache-from: type=local,src=${{ runner.temp }}/.buildx-cache
cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache,mode=max,reset=true
```
+
+## Inline cache
+
+Use individual actions for the [inline cache exporter](../../cache/backends/inline.md).
+However, note that the `inline` cache exporter only supports `min` cache mode.
+To use `max` cache mode, push the image and the cache separately using the
+registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ docker:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Login to Docker Hub
+ uses: docker/login-action@{{% param "login_action_version" %}}
+ with:
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
+
+ - name: Build and push
+ uses: docker/build-push-action@{{% param "build_push_action_version" %}}
+ with:
+ push: true
+ tags: user/app:latest
+ cache-from: type=registry,ref=user/app:latest
+ cache-to: type=inline
+```
+
+## Registry cache
+
+You can import/export cache from a cache manifest or (special) image
+configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md).
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ docker:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Login to Docker Hub
+ uses: docker/login-action@{{% param "login_action_version" %}}
+ with:
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
+
+ - name: Build and push
+ uses: docker/build-push-action@{{% param "build_push_action_version" %}}
+ with:
+ push: true
+ tags: user/app:latest
+ cache-from: type=registry,ref=user/app:buildcache
+ cache-to: type=registry,ref=user/app:buildcache,mode=max
+```
diff --git a/content/manuals/build/ci/github-actions/github-builder/_index.md b/content/manuals/build/ci/github-actions/github-builder/_index.md
index 4322d7968805..37ff2998aecf 100644
--- a/content/manuals/build/ci/github-actions/github-builder/_index.md
+++ b/content/manuals/build/ci/github-actions/github-builder/_index.md
@@ -3,6 +3,7 @@ title: Docker GitHub Builder
linkTitle: GitHub Builder
description: Use Docker-maintained reusable GitHub Actions workflows to build images and artifacts with BuildKit.
keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows
+weight: 10
params:
sidebar:
badge:
@@ -17,52 +18,9 @@ This section explains what the workflows solve, how they differ from wiring
together individual GitHub Actions in each repository, and when to use
[`build.yml`](build.md) or [`bake.yml`](bake.md).
-If you compose a build job from `docker/login-action`, `docker/setup-buildx-action`,
-`docker/metadata-action`, and either `docker/build-push-action` or
-`docker/bake-action`, your repository owns every detail of how the build runs.
-That approach works, but it also means every repository has to maintain its own
-runner selection, [cache setup](../cache.md), [Provenance settings](../attestations.md),
-signing behavior, and [multi-platform manifest handling](../multi-platform.md).
-Docker GitHub Builder moves that implementation into Docker-maintained reusable
-workflows, so your workflow only decides when to build and which inputs to pass.
+## Call a reusable workflow
-The difference is easiest to see in the job definition. A conventional workflow
-spells out each action step:
-
-```yaml
-jobs:
- docker:
- runs-on: ubuntu-latest
- steps:
- - name: Login to Docker Hub
- uses: docker/login-action@{{% param "login_action_version" %}}
- with:
- username: ${{ vars.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-
- - name: Set up QEMU
- uses: docker/setup-qemu-action@{{% param "setup_qemu_action_version" %}}
-
- - name: Set up Docker Buildx
- uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
-
- - name: Docker meta
- uses: docker/metadata-action@{{% param "metadata_action_version" %}}
- id: meta
- with:
- images: name/app
-
- - name: Build and push
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: ${{ github.event_name != 'pull_request' }}
- tags: ${{ steps.meta.outputs.tags }}
- labels: ${{ steps.meta.outputs.labels }}
- cache-from: type=gha
- cache-to: type=gha
-```
-
-With Docker GitHub Builder, the same build is a reusable workflow call:
+Define the build at the job level:
```yaml
jobs:
@@ -74,6 +32,8 @@ jobs:
with:
output: image
push: ${{ github.event_name != 'pull_request' }}
+ cache: true
+ set-meta-labels: true
meta-images: name/app
secrets:
registry-auths: |
@@ -85,12 +45,12 @@ jobs:
This model gives you a build pipeline that is maintained in the Docker
organization, uses a pinned [BuildKit](../../../buildkit/_index.md) environment,
distributes [multi-platform builds](../../../building/multi-platform.md) across
-runners when that helps, and emits signed [SLSA provenance](../../../metadata/attestations/slsa-provenance.md)
-that records both the source commit and the builder identity.
+runners when that helps, and signs [SLSA provenance](../../../metadata/attestations/slsa-provenance.md)
+when publishing images. The provenance records both the source commit and
+the builder identity.
-That tradeoff is intentional. You keep control of when the build runs and which
-inputs it uses, but the build implementation itself lives in the
-Docker-maintained workflow rather than in per-repository job steps.
+You control when the build runs and which inputs it uses. Docker maintains
+the build steps in the reusable workflow.
Use [`build.yml`](build.md) when your repository builds from a Dockerfile and
the familiar `build-push-action` inputs map cleanly to your workflow. Use
@@ -104,4 +64,48 @@ Both workflows support image output, local output, cache export to the
Bake workflow adds Bake definition validation and builds one target per workflow
call.
+## Compose individual actions
+
+Use individual actions when your task needs a local Docker image, a service
+container, custom builder configuration, or files and secrets generated by
+steps on the same runner. Builder's `image` output publishes to a registry;
+its `local` output exports files. Neither loads an image into the caller's
+Docker image store or exports a Docker image archive.
+
+The following action-based job manages setup, metadata, and cache explicitly:
+
+```yaml
+jobs:
+ docker:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Login to Docker Hub
+ if: github.event_name != 'pull_request'
+ uses: docker/login-action@{{% param "login_action_version" %}}
+ with:
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+ - name: Set up QEMU
+ uses: docker/setup-qemu-action@{{% param "setup_qemu_action_version" %}}
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
+
+ - name: Docker meta
+ uses: docker/metadata-action@{{% param "metadata_action_version" %}}
+ id: meta
+ with:
+ images: name/app
+
+ - name: Build and push
+ uses: docker/build-push-action@{{% param "build_push_action_version" %}}
+ with:
+ push: ${{ github.event_name != 'pull_request' }}
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha
+```
+
{{% sectionlinks %}}
diff --git a/content/manuals/build/ci/github-actions/github-builder/bake.md b/content/manuals/build/ci/github-actions/github-builder/bake.md
index c40d4a6314c4..505480b59a87 100644
--- a/content/manuals/build/ci/github-actions/github-builder/bake.md
+++ b/content/manuals/build/ci/github-actions/github-builder/bake.md
@@ -144,6 +144,6 @@ jobs:
With `output: local`, the workflow injects the matching local output override
into the Bake run and merges the uploaded artifacts after the per-platform
-builds finish. If you need a manual Bake pattern that stays in a normal job,
-see [Multi-platform image](../multi-platform.md). If your build does not need a
+builds finish. For a Bake pattern that stays in a normal job,
+see [Annotations with individual actions](../annotations.md#add-annotations-with-individual-actions). If your build does not need a
Bake definition, use [build.yml](build.md) instead.
diff --git a/content/manuals/build/ci/github-actions/manage-tags-labels.md b/content/manuals/build/ci/github-actions/manage-tags-labels.md
index 5e3f0e19158f..ec4e7d08392b 100644
--- a/content/manuals/build/ci/github-actions/manage-tags-labels.md
+++ b/content/manuals/build/ci/github-actions/manage-tags-labels.md
@@ -5,6 +5,64 @@ description: Assign tags and labels to images automatically with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, tags, labels
---
+Use [Docker GitHub Builder](github-builder/build.md) to generate tags and OCI
+labels from GitHub events. Set `meta-images` and `meta-tags` to configure the
+metadata action, and `set-meta-labels: true` to apply the generated labels.
+This workflow publishes to Docker Hub and GitHub Container Registry on push
+and scheduled events, and builds without publishing on pull requests:
+
+```yaml
+name: ci
+
+on:
+ schedule:
+ - cron: "0 10 * * *"
+ push:
+ branches:
+ - "**"
+ tags:
+ - "v*.*.*"
+ pull_request:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ packages: write
+ with:
+ output: image
+ push: ${{ github.event_name != 'pull_request' }}
+ set-meta-labels: true
+ meta-tags: |
+ type=schedule
+ type=ref,event=branch
+ type=ref,event=pr
+ type=semver,pattern={{version}}
+ type=semver,pattern={{major}}.{{minor}}
+ type=semver,pattern={{major}}
+ type=sha
+ meta-images: |
+ name/app
+ ghcr.io/username/app
+ secrets:
+ registry-auths: |
+ - registry: docker.io
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+ - registry: ghcr.io
+ username: ${{ github.repository_owner }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Replace the image names with repositories you can push to. The
+`packages: write` permission authorizes publishing to GitHub Container Registry.
+Builder skips registry login and signing when `push` is false, so fork pull
+requests don't need registry secrets.
+
+## Generate metadata with individual actions
+
If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
for labels, you can do it in a dedicated setup step. The following workflow
will use the [Docker Metadata Action](https://github.com/docker/metadata-action)
diff --git a/content/manuals/build/ci/github-actions/multi-platform.md b/content/manuals/build/ci/github-actions/multi-platform.md
index 1b03149a1257..2ffd99cbac64 100644
--- a/content/manuals/build/ci/github-actions/multi-platform.md
+++ b/content/manuals/build/ci/github-actions/multi-platform.md
@@ -1,10 +1,77 @@
---
title: Multi-platform image with GitHub Actions
linkTitle: Multi-platform image
-description: Build for multiple architectures with GitHub Actions using QEMU emulation or multiple native builders
+description: Build multi-platform images with Docker GitHub Builder or individual actions using QEMU.
keywords: ci, github actions, gha, buildkit, buildx, multi-platform
---
+Use [Docker GitHub Builder](github-builder/_index.md) to build multi-platform
+images across native runners and publish a combined image manifest.
+
+## Distribute build across multiple runners
+
+Building multiple platforms on the same runner can significantly extend build
+times, particularly when dealing with complex Dockerfiles or a high number of
+target platforms. If you want to split platform builds across multiple runners
+without maintaining a custom matrix and merge job, use the
+[Docker GitHub Builder](github-builder/_index.md). The reusable workflows
+compute the per-platform matrix, run each platform on its own runner, and
+create the final manifest for you.
+
+The following workflow uses the [`build.yml` reusable workflow](github-builder/build.md)
+to distribute a multi-platform Dockerfile build:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ push: true
+ platforms: linux/amd64,linux/arm64
+ meta-images: user/app
+ meta-tags: |
+ type=ref,event=branch
+ type=ref,event=pr
+ type=semver,pattern={{version}}
+ type=semver,pattern={{major}}.{{minor}}
+ secrets:
+ registry-auths: |
+ - registry: docker.io
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+```
+
+With `distribute: true`, which is the default, the workflow splits the build
+into one platform per runner and assembles the final multi-platform image in
+its finalize phase. The default `runner` mapping selects native GitHub-hosted
+Linux runners for Arm and other platforms. To customize the mapping, see [runner selection](github-builder/architecture.md#runner-selection).
+If you need to control the Docker build inputs directly, see
+[Build with Docker GitHub Builder build.yml](github-builder/build.md).
+
+### With Bake
+
+For builds defined in a Bake file, use the
+[Bake reusable workflow](github-builder/bake.md#build-and-push-a-bake-target).
+It distributes the target's platforms and publishes the combined manifest.
+
+## Build with individual actions and QEMU
+
+Use individual actions when you need to configure the job's Docker Engine or
+run other steps alongside the build. The following example uses QEMU to build
+both platforms on one runner.
+
You can build [multi-platform images](../../building/multi-platform.md) using
the `platforms` option, as shown in the following example:
@@ -94,128 +161,3 @@ jobs:
load: true
tags: user/app:latest
```
-
-## Distribute build across multiple runners
-
-Building multiple platforms on the same runner can significantly extend build
-times, particularly when dealing with complex Dockerfiles or a high number of
-target platforms. If you want to split platform builds across multiple runners
-without maintaining a custom matrix and merge job, use the
-[Docker GitHub Builder](github-builder/_index.md). The reusable workflows
-compute the per-platform matrix, run each platform on its own runner, and
-create the final manifest for you.
-
-The following workflow uses the [`build.yml` reusable workflow](github-builder/build.md)
-to distribute a multi-platform Dockerfile build:
-
-```yaml
-name: ci
-
-on:
- push:
-
-permissions:
- contents: read
-
-jobs:
- build:
- uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
- permissions:
- contents: read
- id-token: write
- with:
- output: image
- push: true
- platforms: linux/amd64,linux/arm64
- meta-images: user/app
- meta-tags: |
- type=ref,event=branch
- type=ref,event=pr
- type=semver,pattern={{version}}
- type=semver,pattern={{major}}.{{minor}}
- secrets:
- registry-auths: |
- - registry: docker.io
- username: ${{ vars.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-```
-
-With `distribute: true`, which is the default, the workflow splits the build
-into one platform per runner and assembles the final multi-platform image in
-its finalize phase. The default `runner` mapping sends Linux Arm platforms to
-`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To customize
-the mapping, see [runner selection](github-builder/architecture.md#runner-selection).
-If you need to control the Docker build inputs directly, see
-[Build with Docker GitHub Builder build.yml](github-builder/build.md).
-
-### With Bake
-
-You can use the [`bake.yml` reusable workflow](github-builder/bake.md) for the
-same pattern when your build is defined in a Bake file. The workflow reads the
-target platforms from the Bake definition, distributes the per-platform builds,
-and publishes the final manifest without a separate prepare or merge job.
-
-```hcl
-variable "DEFAULT_TAG" {
- default = "app:local"
-}
-
-// Special target: https://github.com/docker/metadata-action#bake-definition
-target "docker-metadata-action" {
- tags = ["${DEFAULT_TAG}"]
-}
-
-// Default target if none specified
-group "default" {
- targets = ["image-local"]
-}
-
-target "image" {
- inherits = ["docker-metadata-action"]
-}
-
-target "image-local" {
- inherits = ["image"]
- output = ["type=docker"]
-}
-
-target "image-all" {
- inherits = ["image"]
- platforms = [
- "linux/amd64",
- "linux/arm/v6",
- "linux/arm/v7",
- "linux/arm64"
- ]
-}
-```
-
-```yaml
-name: ci
-
-on:
- push:
-
-permissions:
- contents: read
-
-jobs:
- bake:
- uses: docker/github-builder/.github/workflows/bake.yml@{{% param "github_builder_version" %}}
- permissions:
- contents: read
- id-token: write
- with:
- output: image
- push: true
- target: image-all
- meta-images: user/app
- meta-tags: |
- type=ref,event=branch
- type=sha
- secrets:
- registry-auths: |
- - registry: docker.io
- username: ${{ vars.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-```
diff --git a/content/manuals/build/ci/github-actions/push-multi-registries.md b/content/manuals/build/ci/github-actions/push-multi-registries.md
index e80bbc456b45..a2b2a1c654de 100644
--- a/content/manuals/build/ci/github-actions/push-multi-registries.md
+++ b/content/manuals/build/ci/github-actions/push-multi-registries.md
@@ -5,6 +5,49 @@ description: Push to multiple registries with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry
---
+Use [Docker GitHub Builder](github-builder/build.md) to publish to multiple
+registries. List the image names in `meta-images` and credentials in the
+`registry-auths` secret. This example publishes `latest` and `1.0.0` tags to
+Docker Hub and GitHub Container Registry:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ packages: write
+ with:
+ output: image
+ push: true
+ platforms: linux/amd64,linux/arm64
+ meta-tags: |
+ type=raw,value=latest
+ type=raw,value=1.0.0
+ meta-images: |
+ user/app
+ ghcr.io/user/app
+ secrets:
+ registry-auths: |
+ - registry: docker.io
+ username: ${{ vars.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+ - registry: ghcr.io
+ username: ${{ github.repository_owner }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Replace the image names with repositories you can push to. The
+`packages: write` permission authorizes publishing to GitHub Container Registry.
+
+## Push with individual actions
+
The following workflow will connect you to Docker Hub and GitHub Container
Registry, and push the image to both registries:
@@ -16,6 +59,9 @@ on:
jobs:
docker:
+ permissions:
+ contents: read
+ packages: write
runs-on: ubuntu-latest
steps:
- name: Login to Docker Hub
diff --git a/content/manuals/build/ci/github-actions/reproducible-builds.md b/content/manuals/build/ci/github-actions/reproducible-builds.md
index 0649ca534934..3236aa2bea0c 100644
--- a/content/manuals/build/ci/github-actions/reproducible-builds.md
+++ b/content/manuals/build/ci/github-actions/reproducible-builds.md
@@ -12,13 +12,41 @@ image index, config, and file metadata reflect the specified Unix time.
[source_date_epoch]: https://reproducible-builds.org/docs/source-date-epoch/
-To set the environment variable in GitHub Actions,
-use the built-in `env` property on the build step.
+With Docker GitHub Builder, pass `SOURCE_DATE_EPOCH` as a build argument.
+With individual actions, use the built-in `env` property on the build step.
## Unix epoch timestamps
The following example sets the `SOURCE_DATE_EPOCH` variable to 0, Unix epoch.
+### Set the epoch with Builder
+
+Pass the fixed epoch through the [Build workflow](github-builder/build.md):
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ build-args: |
+ SOURCE_DATE_EPOCH=0
+ meta-images: user/app
+```
+
+For the [Bake workflow](github-builder/bake.md), set
+`*.args.SOURCE_DATE_EPOCH=0` using the `set` input.
+
+### Set the epoch with individual actions
+
{{< tabs group="action" >}}
{{< tab name="`docker/build-push-action`" >}}
@@ -70,7 +98,10 @@ jobs:
## Git commit timestamps
-The following example sets `SOURCE_DATE_EPOCH` to the Git commit timestamp.
+The following individual-action examples set `SOURCE_DATE_EPOCH` to the Git
+commit timestamp. Keep timestamp generation in the caller when it depends on
+a workflow step. A reusable workflow call cannot reference earlier steps in
+the same job.
{{< tabs group="action" >}}
{{< tab name="`docker/build-push-action`" >}}
diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md
index edc7b045c47d..a0a65961c7a4 100644
--- a/content/manuals/build/ci/github-actions/secrets.md
+++ b/content/manuals/build/ci/github-actions/secrets.md
@@ -29,6 +29,41 @@ FROM alpine
RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ...
```
+### Pass secret values with Builder
+
+Pass secret values to [Docker GitHub Builder](github-builder/build.md) using
+the `build-secrets` workflow secret. Its value is a YAML mapping from secret
+IDs to values, rather than the action's `id=value` list:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ build:
+ uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
+ permissions:
+ contents: read
+ id-token: write
+ with:
+ output: image
+ platforms: linux/amd64,linux/arm64
+ meta-images: user/app
+ secrets:
+ build-secrets: |
+ github_token: ${{ toJSON(secrets.GITHUB_TOKEN) }}
+```
+
+The Dockerfile consumes the `github_token` secret in the same way with either
+workflow. `toJSON` quotes the value for the YAML mapping.
+For files, environment variables, or SSH agents prepared by earlier steps,
+use the individual-action examples below. The reusable build runs in separate
+jobs and doesn't share the caller's filesystem or SSH agent.
+
+### Pass secret values with individual actions
+
In this example, the secret name is `github_token`. The following workflow
exposes this secret using the `secrets` input:
@@ -257,8 +292,7 @@ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
### Multi-line secrets
If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
-and need to handle multi-line value, you will need to place the key-value pair
-between quotes:
+with individual actions, place multi-line key-value pairs between quotes:
```yaml
secrets: |
From 182ebda2cc3b48ec298335409bd3f4415c038394 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 30 Oct 2026 13:05:45 +0000
Subject: [PATCH 2/7] docs: integrate Builder guides into GitHub Actions
navigation
The separate Builder subsection duplicates the preferred introduction and action comparison. Move its build, Bake, and architecture guides into the main GitHub Actions section, consolidate the overview, and preserve old page URLs and fragments.
---
.../manuals/build/ci/github-actions/_index.md | 20 +++-
.../build/ci/github-actions/annotations.md | 2 +-
.../build/ci/github-actions/attestations.md | 2 +-
.../bake.md => bake-workflow.md} | 20 ++--
.../build.md => build-workflow.md} | 22 ++--
.../manuals/build/ci/github-actions/cache.md | 4 +-
.../images/architecture-overview.png | Bin
.../images/execution-flow.png | Bin
.../index.md} | 18 +--
.../github-actions/github-builder/_index.md | 111 ------------------
.../ci/github-actions/manage-tags-labels.md | 2 +-
.../build/ci/github-actions/multi-platform.md | 12 +-
.../github-actions/push-multi-registries.md | 2 +-
.../ci/github-actions/reproducible-builds.md | 4 +-
.../build/ci/github-actions/secrets.md | 2 +-
15 files changed, 64 insertions(+), 157 deletions(-)
rename content/manuals/build/ci/github-actions/{github-builder/bake.md => bake-workflow.md} (86%)
rename content/manuals/build/ci/github-actions/{github-builder/build.md => build-workflow.md} (86%)
rename content/manuals/build/ci/github-actions/{github-builder => github-builder-architecture}/images/architecture-overview.png (100%)
rename content/manuals/build/ci/github-actions/{github-builder => github-builder-architecture}/images/execution-flow.png (100%)
rename content/manuals/build/ci/github-actions/{github-builder/architecture.md => github-builder-architecture/index.md} (92%)
delete mode 100644 content/manuals/build/ci/github-actions/github-builder/_index.md
diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md
index c0c3215f5fe3..491546681ec0 100644
--- a/content/manuals/build/ci/github-actions/_index.md
+++ b/content/manuals/build/ci/github-actions/_index.md
@@ -4,13 +4,14 @@ linkTitle: GitHub Actions
description: Build and publish images with Docker GitHub Builder or individual Docker GitHub Actions.
keywords: ci, github actions, gha, build, introduction, tutorial
aliases:
+ - /build/ci/github-actions/github-builder/
- /guides/gha/
- /ci-cd/github-actions/
- /build/ci/github-actions/examples/
---
GitHub Actions automates your build, test, and deployment pipeline. Use
-[Docker GitHub Builder](github-builder/_index.md) to build and publish images
+Docker GitHub Builder to build and publish images
with Docker-maintained reusable workflows. Builder manages Buildx setup,
platform distribution, metadata, and signing. Start with Builder for supported
build tasks, and compose individual actions when you need custom job steps or
@@ -39,6 +40,8 @@ Add your Docker Hub credentials to your GitHub repository:
4. Under **Variables**, create a repository variable named `DOCKERHUB_USERNAME`
containing your Docker Hub username.
+
+
### Set up your GitHub Actions workflow
Create `.github/workflows/docker-ci.yml` in your repository with the following
@@ -77,7 +80,7 @@ Call the reusable workflow with `uses` at the job level, rather than inside
`steps`. Grant `contents: read` to fetch the repository and `id-token: write`
for signing with GitHub's OpenID Connect token. With the default `sign: auto`,
Builder signs attestation manifests when pushing an image. See the
-[Build workflow](github-builder/build.md) for inputs and outputs.
+[Build workflow](build-workflow.md) for inputs and outputs.
Commit the workflow file and push it to your default branch to run it. The
workflow also runs on pull requests. With `push: false`, the default
@@ -101,12 +104,21 @@ see [Test before push](test-before-push.md). For additional build options, see
[Multi-platform images](multi-platform.md) and
[SBOM and provenance attestations](attestations.md).
+Use the [Build workflow](build-workflow.md) for Dockerfile inputs, or the
+[Bake workflow](bake-workflow.md) for a build defined in Bake. Both support
+image and local file output. For details on platform distribution and outputs,
+see [Builder architecture](github-builder-architecture/index.md).
+
+
+
## Build with individual actions
Use individual actions to load images into a job's Docker image store, run
steps before or after a build on the same runner, or configure the builder
-directly. The following alternative uses the same credentials, triggers, and
-metadata as the Builder example:
+directly. Builder's `image` output publishes to a registry; its `local` output
+exports files. Neither loads an image into the caller's Docker image store or
+exports a Docker image archive. The following alternative uses the same
+credentials, triggers, and metadata as the Builder example:
```yaml
name: Build and push Docker image
diff --git a/content/manuals/build/ci/github-actions/annotations.md b/content/manuals/build/ci/github-actions/annotations.md
index c5527a15107b..43e4b342744f 100644
--- a/content/manuals/build/ci/github-actions/annotations.md
+++ b/content/manuals/build/ci/github-actions/annotations.md
@@ -10,7 +10,7 @@ as manifests, indexes, and descriptors.
## Add annotations with Builder
-Use [Docker GitHub Builder](github-builder/build.md) with
+Use [Docker GitHub Builder](build-workflow.md) with
`set-meta-annotations: true` to apply annotations generated by the metadata
action. The `annotations` input also accepts explicit annotations. This
example adds a description to the final image index:
diff --git a/content/manuals/build/ci/github-actions/attestations.md b/content/manuals/build/ci/github-actions/attestations.md
index e81206a2a06e..47bfe9714b30 100644
--- a/content/manuals/build/ci/github-actions/attestations.md
+++ b/content/manuals/build/ci/github-actions/attestations.md
@@ -11,7 +11,7 @@ your image, and how it was built.
## Add attestations with Builder
-[Docker GitHub Builder](github-builder/build.md) manages provenance and signing
+[Docker GitHub Builder](build-workflow.md) manages provenance and signing
in the reusable workflow. It uses max-level provenance for public repositories
and min-level provenance for private repositories. These levels aren't caller
inputs. Use individual actions below if you need to override the provenance
diff --git a/content/manuals/build/ci/github-actions/github-builder/bake.md b/content/manuals/build/ci/github-actions/bake-workflow.md
similarity index 86%
rename from content/manuals/build/ci/github-actions/github-builder/bake.md
rename to content/manuals/build/ci/github-actions/bake-workflow.md
index 505480b59a87..191837e7f048 100644
--- a/content/manuals/build/ci/github-actions/github-builder/bake.md
+++ b/content/manuals/build/ci/github-actions/bake-workflow.md
@@ -3,11 +3,13 @@ title: Bake with Docker GitHub Builder
linkTitle: Bake workflow
description: Use the Docker GitHub Builder bake.yml reusable workflow to build images and local artifacts from a Bake definition.
keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflow
-weight: 30
+aliases:
+ - /build/ci/github-actions/github-builder/bake/
+weight: 20
---
The [`bake.yml` reusable workflow](https://github.com/docker/github-builder?tab=readme-ov-file#bake-reusable-workflow)
-builds from a [Bake definition](../../../bake/_index.md) instead of a Dockerfile
+builds from a [Bake definition](../../bake/_index.md) instead of a Dockerfile
input set. This page shows how to call the workflow for a target, how to pass
Bake overrides and variables, and how to export local output when a Bake file
is already the source of truth for your build.
@@ -15,7 +17,7 @@ is already the source of truth for your build.
## Build and push a Bake target
The following workflow builds the `image` target from `docker-bake.hcl` and
-publishes the result with tags generated from [metadata inputs](../manage-tags-labels.md):
+publishes the result with tags generated from [metadata inputs](manage-tags-labels.md):
```yaml
name: ci
@@ -54,14 +56,14 @@ jobs:
```
Bake workflows build one target per workflow call. Groups and multi-target
-builds aren't supported because [SLSA provenance](../attestations.md), digest
+builds aren't supported because [SLSA provenance](attestations.md), digest
handling, and manifest creation are scoped to a single target.
The workflow validates the definition before the build starts and resolves
the target from the files you pass in `files`. Runner selection uses the same
`runner` input as the Build workflow. Set a single GitHub-hosted Linux runner
label or a platform mapping when the default mapping is not enough. For details,
-see [runner selection](architecture.md#runner-selection).
+see [runner selection](github-builder-architecture/index.md#runner-selection).
## Override target values and variables
@@ -109,8 +111,8 @@ jobs:
This form fits repositories that already use Bake groups, target inheritance,
and variable expansion. The reusable workflow takes care of Buildx setup,
-[GitHub Actions cache export](../../../cache/backends/gha.md),
-[Provenance defaults](../../../metadata/attestations/slsa-provenance.md),
+[GitHub Actions cache export](../../cache/backends/gha.md),
+[Provenance defaults](../../metadata/attestations/slsa-provenance.md),
signing behavior, and the final multi-platform manifest. Metadata labels and
annotations can be merged into the Bake definition without adding a separate
metadata step to your workflow.
@@ -145,5 +147,5 @@ jobs:
With `output: local`, the workflow injects the matching local output override
into the Bake run and merges the uploaded artifacts after the per-platform
builds finish. For a Bake pattern that stays in a normal job,
-see [Annotations with individual actions](../annotations.md#add-annotations-with-individual-actions). If your build does not need a
-Bake definition, use [build.yml](build.md) instead.
+see [Annotations with individual actions](annotations.md#add-annotations-with-individual-actions). If your build does not need a
+Bake definition, use [build.yml](build-workflow.md) instead.
diff --git a/content/manuals/build/ci/github-actions/github-builder/build.md b/content/manuals/build/ci/github-actions/build-workflow.md
similarity index 86%
rename from content/manuals/build/ci/github-actions/github-builder/build.md
rename to content/manuals/build/ci/github-actions/build-workflow.md
index 46f15d37ee21..6040bedc4b68 100644
--- a/content/manuals/build/ci/github-actions/github-builder/build.md
+++ b/content/manuals/build/ci/github-actions/build-workflow.md
@@ -3,13 +3,15 @@ title: Build with Docker GitHub Builder
linkTitle: Build workflow
description: Use the Docker GitHub Builder build.yml reusable workflow to build images and local artifacts from a Dockerfile.
keywords: ci, github actions, gha, buildkit, buildx, reusable workflow, dockerfile
-weight: 20
+aliases:
+ - /build/ci/github-actions/github-builder/build/
+weight: 10
---
The [`build.yml` reusable workflow](https://github.com/docker/github-builder?tab=readme-ov-file#build-reusable-workflow)
builds from a Dockerfile and packages the same core tasks that many repositories
wire together by hand. This page shows how to call the workflow, publish
-[multi-platform images](../../../building/multi-platform.md), and export local
+[multi-platform images](../../building/multi-platform.md), and export local
build artifacts without rebuilding the job structure in every repository.
## Build and push an image
@@ -54,14 +56,14 @@ jobs:
```
When you set `output: image`, `meta-images` is required because the workflow
-creates image names and [manifest tags](../manage-tags-labels.md) from that
+creates image names and [manifest tags](manage-tags-labels.md) from that
input. `distribute: true` is the default, so a multi-platform build can fan out
across native GitHub-hosted runners instead of forcing the whole build onto one
machine. The default `runner` mapping sends Linux Arm platforms to
`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To change that
-mapping, see [runner selection](architecture.md#runner-selection). `sign: auto`
+mapping, see [runner selection](github-builder-architecture/index.md#runner-selection). `sign: auto`
is also the default, which means the workflow signs
-[attestation manifests](../attestations.md) when the image is pushed.
+[attestation manifests](attestations.md) when the image is pushed.
## Export local output as an artifact
@@ -144,9 +146,9 @@ jobs:
This is a Dockerfile build, so the inputs map closely to
`docker/build-push-action`. The difference is that the reusable workflow owns
-Buildx setup, [BuildKit](../../../buildkit/_index.md) configuration,
-[SLSA provenance](../../../metadata/attestations/slsa-provenance.md) mode,
-[GitHub Actions cache backend](../../../cache/backends/gha.md) wiring, signing,
+Buildx setup, [BuildKit](../../buildkit/_index.md) configuration,
+[SLSA provenance](../../metadata/attestations/slsa-provenance.md) mode,
+[GitHub Actions cache backend](../../cache/backends/gha.md) wiring, signing,
and manifest creation. If you need more background on metadata or platform
-distribution, see [Manage tags and labels](../manage-tags-labels.md) and
-[Multi-platform image](../multi-platform.md).
+distribution, see [Manage tags and labels](manage-tags-labels.md) and
+[Multi-platform image](multi-platform.md).
diff --git a/content/manuals/build/ci/github-actions/cache.md b/content/manuals/build/ci/github-actions/cache.md
index 0bc1530cbf8f..407f91844fb6 100644
--- a/content/manuals/build/ci/github-actions/cache.md
+++ b/content/manuals/build/ci/github-actions/cache.md
@@ -18,7 +18,7 @@ and cache mounts.
### Enable cache with Builder
-[Docker GitHub Builder](github-builder/build.md) disables caching by default.
+[Docker GitHub Builder](build-workflow.md) disables caching by default.
Set `cache: true` to import and export GitHub Actions cache. Set
`cache-mode: max` to export intermediate layers, and use `cache-scope` to
separate builds for different images. Builder adds the platform to the scope
@@ -50,7 +50,7 @@ jobs:
password: ${{ secrets.DOCKERHUB_TOKEN }}
```
-The same cache inputs are available with the [Bake workflow](github-builder/bake.md).
+The same cache inputs are available with the [Bake workflow](bake-workflow.md).
See [cache write restrictions](#cache-write-restrictions) for event restrictions.
Builder's `cache-mode` input selects the layers to export (`min` or `max`);
it doesn't grant cache write access.
diff --git a/content/manuals/build/ci/github-actions/github-builder/images/architecture-overview.png b/content/manuals/build/ci/github-actions/github-builder-architecture/images/architecture-overview.png
similarity index 100%
rename from content/manuals/build/ci/github-actions/github-builder/images/architecture-overview.png
rename to content/manuals/build/ci/github-actions/github-builder-architecture/images/architecture-overview.png
diff --git a/content/manuals/build/ci/github-actions/github-builder/images/execution-flow.png b/content/manuals/build/ci/github-actions/github-builder-architecture/images/execution-flow.png
similarity index 100%
rename from content/manuals/build/ci/github-actions/github-builder/images/execution-flow.png
rename to content/manuals/build/ci/github-actions/github-builder-architecture/images/execution-flow.png
diff --git a/content/manuals/build/ci/github-actions/github-builder/architecture.md b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
similarity index 92%
rename from content/manuals/build/ci/github-actions/github-builder/architecture.md
rename to content/manuals/build/ci/github-actions/github-builder-architecture/index.md
index bcb3bddda746..8c3fe37a5d4c 100644
--- a/content/manuals/build/ci/github-actions/github-builder/architecture.md
+++ b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
@@ -1,9 +1,11 @@
---
title: Docker GitHub Builder architecture
-linkTitle: Architecture
+linkTitle: Builder architecture
description: Learn about the architecture of Docker GitHub Builder, a set of reusable workflows for building images and artifacts with BuildKit in GitHub Actions.
keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows
-weight: 10
+aliases:
+ - /build/ci/github-actions/github-builder/architecture/
+weight: 30
---
Docker GitHub Builder separates repository orchestration from build
@@ -18,9 +20,9 @@ signing, and multi-platform assembly in one Docker-maintained path.
## Core architecture
-A caller workflow invokes either [`build.yml`](build.md) or [`bake.yml`](bake.md).
-[`build.yml`](build.md) is the entrypoint for Dockerfile-oriented builds.
-[`bake.yml`](bake.md) is the entrypoint for Bake-oriented builds, where the
+A caller workflow invokes either [`build.yml`](../build-workflow.md) or [`bake.yml`](../bake-workflow.md).
+[`build.yml`](../build-workflow.md) is the entrypoint for Dockerfile-oriented builds.
+[`bake.yml`](../bake-workflow.md) 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
@@ -96,13 +98,13 @@ BuildKit, caching, or manifest assembly were wired together.
## The two reusable entrypoints
-[`build.yml`](build.md) is the better fit when the build is already expressed as
+[`build.yml`](../build-workflow.md) 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`](bake.md) is the better fit when the repository already uses Bake
+[`bake.yml`](../bake-workflow.md) 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
@@ -124,7 +126,7 @@ selection and per-platform assembly.
### Dockerfile-oriented image build
The following example shows the shape of a multi-platform image build driven
-by [`build.yml`](build.md).
+by [`build.yml`](../build-workflow.md).
```yaml
name: ci
diff --git a/content/manuals/build/ci/github-actions/github-builder/_index.md b/content/manuals/build/ci/github-actions/github-builder/_index.md
deleted file mode 100644
index 37ff2998aecf..000000000000
--- a/content/manuals/build/ci/github-actions/github-builder/_index.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-title: Docker GitHub Builder
-linkTitle: GitHub Builder
-description: Use Docker-maintained reusable GitHub Actions workflows to build images and artifacts with BuildKit.
-keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows
-weight: 10
-params:
- sidebar:
- badge:
- color: green
- text: New
----
-
-Docker GitHub Builder is a set of [reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
-in the [`docker/github-builder` repository](https://github.com/docker/github-builder)
-for building container images and local artifacts with [BuildKit](../../../buildkit/_index.md).
-This section explains what the workflows solve, how they differ from wiring
-together individual GitHub Actions in each repository, and when to use
-[`build.yml`](build.md) or [`bake.yml`](bake.md).
-
-## Call a reusable workflow
-
-Define the build at the job level:
-
-```yaml
-jobs:
- build:
- uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
- 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' }}
- cache: true
- set-meta-labels: true
- meta-images: name/app
- secrets:
- registry-auths: |
- - registry: docker.io
- username: ${{ vars.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-```
-
-This model gives you a build pipeline that is maintained in the Docker
-organization, uses a pinned [BuildKit](../../../buildkit/_index.md) environment,
-distributes [multi-platform builds](../../../building/multi-platform.md) across
-runners when that helps, and signs [SLSA provenance](../../../metadata/attestations/slsa-provenance.md)
-when publishing images. The provenance records both the source commit and
-the builder identity.
-
-You control when the build runs and which inputs it uses. Docker maintains
-the build steps in the reusable workflow.
-
-Use [`build.yml`](build.md) when your repository builds from a Dockerfile and
-the familiar `build-push-action` inputs map cleanly to your workflow. Use
-[`bake.yml`](bake.md) when your repository already describes builds in a
-[Bake definition](../../../bake/_index.md), or when you want Bake targets,
-overrides, and variables to stay as the source of truth.
-
-Both workflows support image output, local output, cache export to the
-[GitHub Actions cache backend](../../../cache/backends/gha.md),
-[SBOM generation](../../../metadata/attestations/sbom.md), and signing. The
-Bake workflow adds Bake definition validation and builds one target per workflow
-call.
-
-## Compose individual actions
-
-Use individual actions when your task needs a local Docker image, a service
-container, custom builder configuration, or files and secrets generated by
-steps on the same runner. Builder's `image` output publishes to a registry;
-its `local` output exports files. Neither loads an image into the caller's
-Docker image store or exports a Docker image archive.
-
-The following action-based job manages setup, metadata, and cache explicitly:
-
-```yaml
-jobs:
- docker:
- runs-on: ubuntu-latest
- steps:
- - name: Login to Docker Hub
- if: github.event_name != 'pull_request'
- uses: docker/login-action@{{% param "login_action_version" %}}
- with:
- username: ${{ vars.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-
- - name: Set up QEMU
- uses: docker/setup-qemu-action@{{% param "setup_qemu_action_version" %}}
-
- - name: Set up Docker Buildx
- uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
-
- - name: Docker meta
- uses: docker/metadata-action@{{% param "metadata_action_version" %}}
- id: meta
- with:
- images: name/app
-
- - name: Build and push
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: ${{ github.event_name != 'pull_request' }}
- tags: ${{ steps.meta.outputs.tags }}
- labels: ${{ steps.meta.outputs.labels }}
- cache-from: type=gha
- cache-to: type=gha
-```
-
-{{% sectionlinks %}}
diff --git a/content/manuals/build/ci/github-actions/manage-tags-labels.md b/content/manuals/build/ci/github-actions/manage-tags-labels.md
index ec4e7d08392b..f79940365035 100644
--- a/content/manuals/build/ci/github-actions/manage-tags-labels.md
+++ b/content/manuals/build/ci/github-actions/manage-tags-labels.md
@@ -5,7 +5,7 @@ description: Assign tags and labels to images automatically with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, tags, labels
---
-Use [Docker GitHub Builder](github-builder/build.md) to generate tags and OCI
+Use [Docker GitHub Builder](build-workflow.md) to generate tags and OCI
labels from GitHub events. Set `meta-images` and `meta-tags` to configure the
metadata action, and `set-meta-labels: true` to apply the generated labels.
This workflow publishes to Docker Hub and GitHub Container Registry on push
diff --git a/content/manuals/build/ci/github-actions/multi-platform.md b/content/manuals/build/ci/github-actions/multi-platform.md
index 2ffd99cbac64..9cb4894e3da3 100644
--- a/content/manuals/build/ci/github-actions/multi-platform.md
+++ b/content/manuals/build/ci/github-actions/multi-platform.md
@@ -5,7 +5,7 @@ description: Build multi-platform images with Docker GitHub Builder or individua
keywords: ci, github actions, gha, buildkit, buildx, multi-platform
---
-Use [Docker GitHub Builder](github-builder/_index.md) to build multi-platform
+Use [Docker GitHub Builder](_index.md) to build multi-platform
images across native runners and publish a combined image manifest.
## Distribute build across multiple runners
@@ -14,11 +14,11 @@ Building multiple platforms on the same runner can significantly extend build
times, particularly when dealing with complex Dockerfiles or a high number of
target platforms. If you want to split platform builds across multiple runners
without maintaining a custom matrix and merge job, use the
-[Docker GitHub Builder](github-builder/_index.md). The reusable workflows
+[Docker GitHub Builder](_index.md). The reusable workflows
compute the per-platform matrix, run each platform on its own runner, and
create the final manifest for you.
-The following workflow uses the [`build.yml` reusable workflow](github-builder/build.md)
+The following workflow uses the [`build.yml` reusable workflow](build-workflow.md)
to distribute a multi-platform Dockerfile build:
```yaml
@@ -56,14 +56,14 @@ jobs:
With `distribute: true`, which is the default, the workflow splits the build
into one platform per runner and assembles the final multi-platform image in
its finalize phase. The default `runner` mapping selects native GitHub-hosted
-Linux runners for Arm and other platforms. To customize the mapping, see [runner selection](github-builder/architecture.md#runner-selection).
+Linux runners for Arm and other platforms. To customize the mapping, see [runner selection](github-builder-architecture/index.md#runner-selection).
If you need to control the Docker build inputs directly, see
-[Build with Docker GitHub Builder build.yml](github-builder/build.md).
+[Build with Docker GitHub Builder build.yml](build-workflow.md).
### With Bake
For builds defined in a Bake file, use the
-[Bake reusable workflow](github-builder/bake.md#build-and-push-a-bake-target).
+[Bake reusable workflow](bake-workflow.md#build-and-push-a-bake-target).
It distributes the target's platforms and publishes the combined manifest.
## Build with individual actions and QEMU
diff --git a/content/manuals/build/ci/github-actions/push-multi-registries.md b/content/manuals/build/ci/github-actions/push-multi-registries.md
index a2b2a1c654de..8b2a6a237f41 100644
--- a/content/manuals/build/ci/github-actions/push-multi-registries.md
+++ b/content/manuals/build/ci/github-actions/push-multi-registries.md
@@ -5,7 +5,7 @@ description: Push to multiple registries with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry
---
-Use [Docker GitHub Builder](github-builder/build.md) to publish to multiple
+Use [Docker GitHub Builder](build-workflow.md) to publish to multiple
registries. List the image names in `meta-images` and credentials in the
`registry-auths` secret. This example publishes `latest` and `1.0.0` tags to
Docker Hub and GitHub Container Registry:
diff --git a/content/manuals/build/ci/github-actions/reproducible-builds.md b/content/manuals/build/ci/github-actions/reproducible-builds.md
index 3236aa2bea0c..1d4c3a54aea6 100644
--- a/content/manuals/build/ci/github-actions/reproducible-builds.md
+++ b/content/manuals/build/ci/github-actions/reproducible-builds.md
@@ -21,7 +21,7 @@ The following example sets the `SOURCE_DATE_EPOCH` variable to 0, Unix epoch.
### Set the epoch with Builder
-Pass the fixed epoch through the [Build workflow](github-builder/build.md):
+Pass the fixed epoch through the [Build workflow](build-workflow.md):
```yaml
name: ci
@@ -42,7 +42,7 @@ jobs:
meta-images: user/app
```
-For the [Bake workflow](github-builder/bake.md), set
+For the [Bake workflow](bake-workflow.md), set
`*.args.SOURCE_DATE_EPOCH=0` using the `set` input.
### Set the epoch with individual actions
diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md
index a0a65961c7a4..86ca09865c7f 100644
--- a/content/manuals/build/ci/github-actions/secrets.md
+++ b/content/manuals/build/ci/github-actions/secrets.md
@@ -31,7 +31,7 @@ RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ...
### Pass secret values with Builder
-Pass secret values to [Docker GitHub Builder](github-builder/build.md) using
+Pass secret values to [Docker GitHub Builder](build-workflow.md) using
the `build-secrets` workflow secret. Its value is a YAML mapping from secret
IDs to values, rather than the action's `id=value` list:
From e531735ae582589e9d413945b8e3240ccd74e93a Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 30 Oct 2026 13:11:29 +0000
Subject: [PATCH 3/7] docs: Use GitHub Builder consistently in workflow guides
Standalone Builder references obscure the name of Docker GitHub Builder. Use GitHub Builder in prose, headings, and navigation while preserving existing heading anchors.
---
.../manuals/build/ci/github-actions/_index.md | 16 ++++++++--------
.../build/ci/github-actions/annotations.md | 2 +-
.../build/ci/github-actions/attestations.md | 4 ++--
content/manuals/build/ci/github-actions/cache.md | 6 +++---
.../github-builder-architecture/index.md | 2 +-
.../ci/github-actions/manage-tags-labels.md | 2 +-
.../ci/github-actions/reproducible-builds.md | 2 +-
.../manuals/build/ci/github-actions/secrets.md | 2 +-
8 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md
index 491546681ec0..cc542b0ebd8b 100644
--- a/content/manuals/build/ci/github-actions/_index.md
+++ b/content/manuals/build/ci/github-actions/_index.md
@@ -12,8 +12,8 @@ aliases:
GitHub Actions automates your build, test, and deployment pipeline. Use
Docker GitHub Builder to build and publish images
-with Docker-maintained reusable workflows. Builder manages Buildx setup,
-platform distribution, metadata, and signing. Start with Builder for supported
+with Docker-maintained reusable workflows. GitHub Builder manages Buildx setup,
+platform distribution, metadata, and signing. Start with GitHub Builder for supported
build tasks, and compose individual actions when you need custom job steps or
controls outside the reusable workflow interface.
@@ -79,7 +79,7 @@ jobs:
Call the reusable workflow with `uses` at the job level, rather than inside
`steps`. Grant `contents: read` to fetch the repository and `id-token: write`
for signing with GitHub's OpenID Connect token. With the default `sign: auto`,
-Builder signs attestation manifests when pushing an image. See the
+GitHub Builder signs attestation manifests when pushing an image. See the
[Build workflow](build-workflow.md) for inputs and outputs.
Commit the workflow file and push it to your default branch to run it. The
@@ -89,10 +89,10 @@ Pull requests from forks can build without Docker Hub secrets or a writable
OpenID Connect token. Builds that need private dependencies still need access
to those dependencies.
-Builder checks out the repository for the triggering event in its own jobs.
+GitHub Builder checks out the repository for the triggering event in its own jobs.
Files changed in a caller job aren't automatically available to the build.
-Builder uses the metadata action to generate tags from the GitHub event.
+GitHub Builder uses the metadata action to generate tags from the GitHub event.
For example, a push to `main` publishes `DOCKERHUB_USERNAME/my-image:main`.
The `set-meta-labels` and `set-meta-annotations` switches also apply generated
labels and annotations; both are disabled by default. See
@@ -107,7 +107,7 @@ see [Test before push](test-before-push.md). For additional build options, see
Use the [Build workflow](build-workflow.md) for Dockerfile inputs, or the
[Bake workflow](bake-workflow.md) for a build defined in Bake. Both support
image and local file output. For details on platform distribution and outputs,
-see [Builder architecture](github-builder-architecture/index.md).
+see [GitHub Builder architecture](github-builder-architecture/index.md).
@@ -115,10 +115,10 @@ see [Builder architecture](github-builder-architecture/index.md).
Use individual actions to load images into a job's Docker image store, run
steps before or after a build on the same runner, or configure the builder
-directly. Builder's `image` output publishes to a registry; its `local` output
+directly. GitHub Builder's `image` output publishes to a registry; its `local` output
exports files. Neither loads an image into the caller's Docker image store or
exports a Docker image archive. The following alternative uses the same
-credentials, triggers, and metadata as the Builder example:
+credentials, triggers, and metadata as the GitHub Builder example:
```yaml
name: Build and push Docker image
diff --git a/content/manuals/build/ci/github-actions/annotations.md b/content/manuals/build/ci/github-actions/annotations.md
index 43e4b342744f..3d9c49b5e45d 100644
--- a/content/manuals/build/ci/github-actions/annotations.md
+++ b/content/manuals/build/ci/github-actions/annotations.md
@@ -8,7 +8,7 @@ keywords: ci, github actions, gha, buildkit, buildx, annotations, oci
Annotations let you specify arbitrary metadata for OCI image components, such
as manifests, indexes, and descriptors.
-## Add annotations with Builder
+## Add annotations with GitHub Builder {#add-annotations-with-builder}
Use [Docker GitHub Builder](build-workflow.md) with
`set-meta-annotations: true` to apply annotations generated by the metadata
diff --git a/content/manuals/build/ci/github-actions/attestations.md b/content/manuals/build/ci/github-actions/attestations.md
index 47bfe9714b30..22f251c0f326 100644
--- a/content/manuals/build/ci/github-actions/attestations.md
+++ b/content/manuals/build/ci/github-actions/attestations.md
@@ -9,7 +9,7 @@ Software Bill of Material (SBOM) and provenance
[attestations](../../metadata/attestations/_index.md) add metadata about the contents of
your image, and how it was built.
-## Add attestations with Builder
+## Add attestations with GitHub Builder {#add-attestations-with-builder}
[Docker GitHub Builder](build-workflow.md) manages provenance and signing
in the reusable workflow. It uses max-level provenance for public repositories
@@ -17,7 +17,7 @@ and min-level provenance for private repositories. These levels aren't caller
inputs. Use individual actions below if you need to override the provenance
level for a private repository.
-Set `sbom: true` to add an SBOM. With the default `sign: auto`, Builder signs
+Set `sbom: true` to add an SBOM. With the default `sign: auto`, GitHub Builder signs
attestation manifests when pushing an image, using the job's `id-token: write`
permission:
diff --git a/content/manuals/build/ci/github-actions/cache.md b/content/manuals/build/ci/github-actions/cache.md
index 407f91844fb6..797b102c9553 100644
--- a/content/manuals/build/ci/github-actions/cache.md
+++ b/content/manuals/build/ci/github-actions/cache.md
@@ -16,12 +16,12 @@ and cache mounts.
## GitHub cache
-### Enable cache with Builder
+### Enable cache with GitHub Builder {#enable-cache-with-builder}
[Docker GitHub Builder](build-workflow.md) disables caching by default.
Set `cache: true` to import and export GitHub Actions cache. Set
`cache-mode: max` to export intermediate layers, and use `cache-scope` to
-separate builds for different images. Builder adds the platform to the scope
+separate builds for different images. GitHub Builder adds the platform to the scope
for distributed builds and makes cache export failures non-fatal.
```yaml
@@ -52,7 +52,7 @@ jobs:
The same cache inputs are available with the [Bake workflow](bake-workflow.md).
See [cache write restrictions](#cache-write-restrictions) for event restrictions.
-Builder's `cache-mode` input selects the layers to export (`min` or `max`);
+GitHub Builder's `cache-mode` input selects the layers to export (`min` or `max`);
it doesn't grant cache write access.
### Cache backend API
diff --git a/content/manuals/build/ci/github-actions/github-builder-architecture/index.md b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
index 8c3fe37a5d4c..0bced95f8634 100644
--- a/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
+++ b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
@@ -1,6 +1,6 @@
---
title: Docker GitHub Builder architecture
-linkTitle: Builder architecture
+linkTitle: GitHub Builder architecture
description: Learn about the architecture of Docker GitHub Builder, a set of reusable workflows for building images and artifacts with BuildKit in GitHub Actions.
keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows
aliases:
diff --git a/content/manuals/build/ci/github-actions/manage-tags-labels.md b/content/manuals/build/ci/github-actions/manage-tags-labels.md
index f79940365035..3d327af90c69 100644
--- a/content/manuals/build/ci/github-actions/manage-tags-labels.md
+++ b/content/manuals/build/ci/github-actions/manage-tags-labels.md
@@ -58,7 +58,7 @@ jobs:
Replace the image names with repositories you can push to. The
`packages: write` permission authorizes publishing to GitHub Container Registry.
-Builder skips registry login and signing when `push` is false, so fork pull
+GitHub Builder skips registry login and signing when `push` is false, so fork pull
requests don't need registry secrets.
## Generate metadata with individual actions
diff --git a/content/manuals/build/ci/github-actions/reproducible-builds.md b/content/manuals/build/ci/github-actions/reproducible-builds.md
index 1d4c3a54aea6..9beaa2692eb0 100644
--- a/content/manuals/build/ci/github-actions/reproducible-builds.md
+++ b/content/manuals/build/ci/github-actions/reproducible-builds.md
@@ -19,7 +19,7 @@ With individual actions, use the built-in `env` property on the build step.
The following example sets the `SOURCE_DATE_EPOCH` variable to 0, Unix epoch.
-### Set the epoch with Builder
+### Set the epoch with GitHub Builder {#set-the-epoch-with-builder}
Pass the fixed epoch through the [Build workflow](build-workflow.md):
diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md
index 86ca09865c7f..51330f11e1d7 100644
--- a/content/manuals/build/ci/github-actions/secrets.md
+++ b/content/manuals/build/ci/github-actions/secrets.md
@@ -29,7 +29,7 @@ FROM alpine
RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ...
```
-### Pass secret values with Builder
+### Pass secret values with GitHub Builder {#pass-secret-values-with-builder}
Pass secret values to [Docker GitHub Builder](build-workflow.md) using
the `build-secrets` workflow secret. Its value is a YAML mapping from secret
From 710505220c5f00ec77ff05e8d7e8310d04cefeb2 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:10:24 +0000
Subject: [PATCH 4/7] docs: use heading attributes for GitHub Actions anchors
Separate HTML anchors duplicate the role of explicit heading IDs. Attach the existing fragment IDs to the workflow headings using Markdown attributes.
---
content/manuals/build/ci/github-actions/_index.md | 8 ++------
1 file changed, 2 insertions(+), 6 deletions(-)
diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md
index cc542b0ebd8b..722b3ba82594 100644
--- a/content/manuals/build/ci/github-actions/_index.md
+++ b/content/manuals/build/ci/github-actions/_index.md
@@ -40,9 +40,7 @@ Add your Docker Hub credentials to your GitHub repository:
4. Under **Variables**, create a repository variable named `DOCKERHUB_USERNAME`
containing your Docker Hub username.
-
-
-### Set up your GitHub Actions workflow
+### Set up your GitHub Actions workflow {#call-a-reusable-workflow}
Create `.github/workflows/docker-ci.yml` in your repository with the following
contents. Replace `my-image` with the name of your Docker Hub repository, and
@@ -109,9 +107,7 @@ Use the [Build workflow](build-workflow.md) for Dockerfile inputs, or the
image and local file output. For details on platform distribution and outputs,
see [GitHub Builder architecture](github-builder-architecture/index.md).
-
-
-## Build with individual actions
+## Build with individual actions {#compose-individual-actions}
Use individual actions to load images into a job's Docker image store, run
steps before or after a build on the same runner, or configure the builder
From fc8f816bae0d4d672e5232d00d149436497f301b Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:15:54 +0000
Subject: [PATCH 5/7] docs: remove GitHub Actions examples list
The GitHub Actions introduction repeats recipe navigation in an Examples section.
Remove that section and its sectionlinks list while retaining the task links in the introduction.
---
content/manuals/build/ci/github-actions/_index.md | 7 -------
1 file changed, 7 deletions(-)
diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md
index 722b3ba82594..4552a300decd 100644
--- a/content/manuals/build/ci/github-actions/_index.md
+++ b/content/manuals/build/ci/github-actions/_index.md
@@ -186,10 +186,3 @@ The following GitHub Actions are available:
multi-platform builds.
- [Docker Scout](https://github.com/docker/scout-action):
analyze Docker images for security vulnerabilities.
-
-## Examples
-
-If you're looking for examples on how to use the Docker GitHub Actions,
-refer to the following sections:
-
-{{% sectionlinks %}}
From 6392d1fa7bbab305fb351892ba444b29e256f459 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:30:11 +0000
Subject: [PATCH 6/7] docs: remove unused sectionlinks shortcode
Removing the GitHub Actions recipe list left its shortcode unused, causing strict Hugo builds to fail. Remove the unreferenced template so validation can build the site.
---
layouts/_shortcodes/sectionlinks.html | 3 ---
1 file changed, 3 deletions(-)
delete mode 100644 layouts/_shortcodes/sectionlinks.html
diff --git a/layouts/_shortcodes/sectionlinks.html b/layouts/_shortcodes/sectionlinks.html
deleted file mode 100644
index 51b9f633e4dd..000000000000
--- a/layouts/_shortcodes/sectionlinks.html
+++ /dev/null
@@ -1,3 +0,0 @@
-{{ range .Page.Pages }}
-- [{{ .Title }}]({{ .RelPermalink }})
-{{ end }}
From 1aeb8e2ab3eb16575b5e341f943e7038124d4e37 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 13 Nov 2026 08:14:15 +0000
Subject: [PATCH 7/7] docs: Correct GitHub Builder examples and runner guidance
The annotation example could overwrite its custom description, and the introduction described a checkout instead of a Git context. Use metadata overrides, clarify which files are built, and link to upstream runner defaults to avoid duplicating changing values.
---
content/manuals/build/ci/github-actions/_index.md | 4 ++--
content/manuals/build/ci/github-actions/annotations.md | 9 +++++----
.../manuals/build/ci/github-actions/build-workflow.md | 6 +++---
.../github-builder-architecture/index.md | 10 ++--------
4 files changed, 12 insertions(+), 17 deletions(-)
diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md
index 4552a300decd..178b7d5f4617 100644
--- a/content/manuals/build/ci/github-actions/_index.md
+++ b/content/manuals/build/ci/github-actions/_index.md
@@ -87,8 +87,8 @@ Pull requests from forks can build without Docker Hub secrets or a writable
OpenID Connect token. Builds that need private dependencies still need access
to those dependencies.
-GitHub Builder checks out the repository for the triggering event in its own jobs.
-Files changed in a caller job aren't automatically available to the build.
+GitHub Builder builds from the repository at the triggering Git reference.
+Files changed in a caller job aren't included in the build.
GitHub Builder uses the metadata action to generate tags from the GitHub event.
For example, a push to `main` publishes `DOCKERHUB_USERNAME/my-image:main`.
diff --git a/content/manuals/build/ci/github-actions/annotations.md b/content/manuals/build/ci/github-actions/annotations.md
index 3d9c49b5e45d..05352e43ad93 100644
--- a/content/manuals/build/ci/github-actions/annotations.md
+++ b/content/manuals/build/ci/github-actions/annotations.md
@@ -12,8 +12,9 @@ as manifests, indexes, and descriptors.
Use [Docker GitHub Builder](build-workflow.md) with
`set-meta-annotations: true` to apply annotations generated by the metadata
-action. The `annotations` input also accepts explicit annotations. This
-example adds a description to the final image index:
+action. Use `meta-annotations` to override generated values while preserving
+the other metadata. This example adds a custom description to the final image
+index:
```yaml
name: ci
@@ -31,8 +32,8 @@ jobs:
output: image
push: true
set-meta-annotations: true
- annotations: |
- index:org.opencontainers.image.description=My application
+ meta-annotations: |
+ org.opencontainers.image.description=My application
meta-images: user/app
secrets:
registry-auths: |
diff --git a/content/manuals/build/ci/github-actions/build-workflow.md b/content/manuals/build/ci/github-actions/build-workflow.md
index 6040bedc4b68..789023557327 100644
--- a/content/manuals/build/ci/github-actions/build-workflow.md
+++ b/content/manuals/build/ci/github-actions/build-workflow.md
@@ -59,9 +59,9 @@ When you set `output: image`, `meta-images` is required because the workflow
creates image names and [manifest tags](manage-tags-labels.md) from that
input. `distribute: true` is the default, so a multi-platform build can fan out
across native GitHub-hosted runners instead of forcing the whole build onto one
-machine. The default `runner` mapping sends Linux Arm platforms to
-`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To change that
-mapping, see [runner selection](github-builder-architecture/index.md#runner-selection). `sign: auto`
+machine. For the default `runner` mapping, see
+[Runner mapping](https://github.com/docker/github-builder#runner-mapping). To change
+that mapping, see [runner selection](github-builder-architecture/index.md#runner-selection). `sign: auto`
is also the default, which means the workflow signs
[attestation manifests](attestations.md) when the image is pushed.
diff --git a/content/manuals/build/ci/github-actions/github-builder-architecture/index.md b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
index 0bced95f8634..c7f3aebca6f6 100644
--- a/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
+++ b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md
@@ -49,14 +49,8 @@ conceptual platform jobs:
The `runner` input accepts either a single GitHub-hosted Linux runner label or a
newline-delimited platform mapping.
-The default value is a platform mapping that uses GitHub-hosted Ubuntu runners:
-
-```yaml
-runner: |
- default=ubuntu-24.04
- linux/arm=ubuntu-24.04-arm
- linux/arm64=ubuntu-24.04-arm
-```
+For the default mapping, see
+[Runner mapping](https://github.com/docker/github-builder#runner-mapping).
In the platform job, the runner label resolves to a single value: