dvdksn · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026
@@ -1,50 +1,21 @@
 ---
 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:
+  - /build/ci/github-actions/github-builder/
   - /guides/gha/
   - /ci-cd/github-actions/
   - /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 to build and publish images
+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.
 
 ## Get started
 
@@ -69,12 +40,82 @@ 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
 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`,
+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
+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.
+
+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 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).
+
+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 [GitHub Builder architecture](github-builder-architecture/index.md).
+
+## 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
+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 GitHub Builder example:
+
 ```yaml
 name: Build and push Docker image
 
@@ -116,34 +157,32 @@ 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.
-
-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.
+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.
 
-## Examples
+### Available actions
 
-If you're looking for examples on how to use the Docker GitHub Actions,
-refer to the following sections:
+The following GitHub Actions are available:
 
-{{% sectionlinks %}}
+- [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.
@@ -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 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
+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" %}}
 

@@ -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 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
+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`, GitHub 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" %}}
 

@@ -3,19 +3,21 @@ 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.
 
 ## 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.
@@ -144,6 +146,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
-Bake definition, use [build.yml](build.md) instead.
+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-workflow.md) instead.