# github-builder-experimental **Repository Path**: mirrors_docker/github-builder-experimental ## Basic Information - **Project Name**: github-builder-experimental - **Description**: Official Docker-maintained reusable GitHub Actions workflows - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-15 - **Last Updated**: 2026-08-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [![Test build workflow](https://img.shields.io/github/actions/workflow/status/docker/github-builder/.test-build.yml?label=test%20build&logo=github&style=flat-square)](https://github.com/docker/github-builder/actions?workflow=.test-build) [![Test bake workflow](https://img.shields.io/github/actions/workflow/status/docker/github-builder/.test-bake.yml?label=test%20bake&logo=github&style=flat-square)](https://github.com/docker/github-builder/actions?workflow=.test-bake) ___ * [Overview](#overview) * [Key Advantages](#key-advantages) * [Performance](#performance) * [Security](#security) * [Isolation & Reliability](#isolation--reliability) * [Build reusable workflow](#build-reusable-workflow) * [Inputs](#inputs) * [Secrets](#secrets) * [Outputs](#outputs) * [Bake reusable workflow](#bake-reusable-workflow) * [Inputs](#inputs-1) * [Secrets](#secrets-1) * [Outputs](#outputs-1) * [Notes](#notes) * [Signed GitHub Actions cache](#signed-github-actions-cache) * [Registry identities](#registry-identities) * [Docker Hub OIDC](#docker-hub-oidc) * [AWS ECR](#aws-ecr) * [Google Artifact Registry](#google-artifact-registry) * [Runner mapping](#runner-mapping) * [Metadata templates](#metadata-templates) ## Overview This repository provides official Docker-maintained [reusable GitHub Actions workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows) to securely build container images and artifacts using Docker best practices. The reusable workflows incorporate functionality from our GitHub Actions like [`docker/build-push-action`](https://github.com/docker/build-push-action/), [`docker/metadata-action`](https://github.com/docker/metadata-action/), etc., into a single workflow: ```yaml name: ci permissions: contents: read on: push: branches: - 'main' tags: - 'v*' pull_request: jobs: build: uses: docker/github-builder/.github/workflows/build.yml@v1 permissions: contents: read # to fetch the repository content id-token: write # for signing attestations and cache entries with GitHub OIDC with: output: image push: ${{ github.event_name != 'pull_request' }} meta-images: name/app secrets: registry-auths: | - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} ``` This workflow provides a trusted BuildKit instance and generates signed SLSA-compliant provenance attestations, guaranteeing the build happened from the source commit and all build steps ran in isolated sandboxed environments from immutable sources. This enables GitHub projects to follow a seamless path toward higher levels of security and trust. ## Key Advantages ### Performance * **Native parallelization for multi-platform builds.** Workflows can automatically distribute builds across runners based on target platform to be built, improving throughput for other architectures without requiring emulation or [custom CI logic](https://docs.docker.com/build/ci/github-actions/multi-platform/#distribute-build-across-multiple-runners) or self-managed runners. * **Optimized cache warming & reuse.** The builder can use the GitHub Actions cache backend to persist layers across branches, PRs, and rebuilds. This significantly reduces cold-start times and avoids repeating expensive dependency installations. With GitHub OIDC available, cache entries are signed and verified before reuse so warm-cache builds do not accept unauthenticated cache contents as build inputs. See [Signed GitHub Actions cache](#signed-github-actions-cache). * **Centralized build configuration.** Repositories no longer need to configure buildx drivers, tune storage, or adjust resource limits. The reusable workflows encapsulate the recommended configuration, providing fast, consistent builds across any project that opts in. ### Security * **Trusted workflows in the Docker organization.** Builds are executed by reusable workflows defined in the [**@docker**](https://github.com/docker) organization, not by arbitrary user-defined workflow steps. Consumers can rely on GitHub's trust model and repository protections on the Docker side (branch protection, code review, signing, etc.) to reason about who controls the build logic. * **Verifiable, immutable sources.** The workflows use the GitHub OIDC token and the exact commit SHA to obtain source and to bind it into SLSA provenance. This ensures that the build is tied to the repository contents as checked in—no additional CI step can silently swap out what is being built. * **Signed SLSA provenance for every build.** BuildKit generates [SLSA-compliant provenance attestation](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) artifacts that are signed with an identity bound to the GitHub workflow. Downstream consumers can verify: - which builder commit produced the image - which source code commit produced the image - which workflow and job executed the build - what inputs and build parameters were used * **Protection from user workflow tampering.** The build steps are pre-defined and optimized in the reusable workflow, and cannot be altered by user configuration. This protects against tampering: preventing untrusted workflow steps from modifying build logic, injecting unexpected flags, or producing misleading provenance. * **Signed cache reuse.** With GitHub OIDC available, all GitHub Actions cache entries produced by these reusable workflows are signed and verified before import. This prevents cache entries produced outside the trusted workflow from being restored while still allowing cache warming and reuse. See [Signed GitHub Actions cache](#signed-github-actions-cache). ### Isolation & Reliability * **Separation between user CI logic and build logic.** The user's workflow orchestrates *when* to build but not *how* to build. The actual build steps live in the Docker-maintained reusable workflows, which cannot be modified from the consuming repository. * **Immutable, reproducible build pipeline.** Builds are driven by declarative inputs (repository commit, build configuration, workflow version). This leads to: - reproducibility (same workflow + same inputs → same outputs) - auditability (inputs and workflow identity recorded in provenance) - reliability (less dependence on ad-hoc per-repo CI scripting) * **Reduced CI variability and config drift.** By reusing the same workflows, projects avoid maintaining custom build logic per repository. Caching, provenance, SBOM generation, and build settings behave uniformly across all adopters. * **Higher assurance for downstream consumers.** Because artifacts are produced by a workflow in the [**@docker**](https://github.com/docker) organization, with SLSA provenance attached, consumers can verify both the *source commit* and the *builder identity* before trusting or promoting an image, an essential part of supply-chain hardening. ## Build reusable workflow The [`build.yml` reusable workflow](.github/workflows/build.yml) lets you build container images and artifacts from a Dockerfile with a user experience similar to [`docker/build-push-action`](https://github.com/docker/build-push-action/). It provides a Docker-maintained, opinionated build pipeline that applies best practices for security, performance, and reliability by default, including isolated execution and signed SLSA provenance while keeping per-repository configuration minimal. ```yaml name: ci permissions: contents: read on: push: branches: - 'main' tags: - 'v*' pull_request: jobs: build: uses: docker/github-builder/.github/workflows/build.yml@v1 permissions: contents: read # to fetch the repository content id-token: write # for signing attestations and cache entries with GitHub OIDC with: output: image push: ${{ github.event_name != 'pull_request' }} platforms: linux/amd64,linux/arm64 meta-images: name/app meta-tags: | type=ref,event=branch type=ref,event=pr type=semver,pattern={{version}} secrets: registry-auths: | - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} ``` ### Inputs > [!NOTE] > `List` type is a newline-delimited string > ```yaml > cache-from: | > user/app:cache > type=local,src=path/to/dir > ``` > > `CSV` type is a comma-delimited string > ```yaml > tags: name/app:latest,name/app:1.0.0 > ``` | Name | Type | Default | Description | |---------------------------|----------|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `runner` | String | See [Runner mapping](#runner-mapping) | GitHub-hosted Linux runner label or platform mapping to build on. See [Runner mapping](#runner-mapping). | | `distribute` | Bool | `true` | Whether to distribute the build across multiple runners (one platform per runner) | | `fail-fast` | Bool | `false` | Whether to cancel all in-progress and queued jobs in the matrix if any job fails | | `job-name-prefix` | String | | Prefix to include in reusable workflow job matrix names in the GitHub Actions UI | | `setup-qemu` | Bool | `false` | Runs the `setup-qemu-action` step to install QEMU static binaries | | `artifact-name` | String | `docker-github-builder-assets` | Name of the uploaded GitHub artifact (for `local` output) | | `artifact-upload` | Bool | `false` | Upload build output GitHub artifact (for `local` output) | | `artifact-retention-days` | Number | `0` | Duration after which artifact will expire in days. `0` means using default retention | | `annotations` | List | | List of annotations to set to the image (for `image` output) | | `build-args` | List | `auto` | List of [build-time variables](https://docs.docker.com/engine/reference/commandline/buildx_build/#build-arg). If you want to set a build-arg through an environment variable, use the `envs` input | | `cache` | Bool | `false` | Enable [GitHub Actions cache](https://docs.docker.com/build/cache/backends/gha/) exporter | | `cache-scope` | String | target name or `buildkit` | Which [scope cache object belongs to](https://docs.docker.com/build/cache/backends/gha/#scope) if `cache` is enabled. This is the cache blob prefix name used when pushing cache to GitHub Actions cache backend | | `cache-mode` | String | `min` | [Cache layers to export](https://docs.docker.com/build/cache/backends/#cache-mode) if cache enabled (`min` or `max`). In `min` cache mode, only layers that are exported into the resulting image are cached, while in `max` cache mode, all layers are cached, even those of intermediate steps | | `context` | String | `.` | Context to build from in the Git working tree | | `file` | String | `{context}/Dockerfile` | Path to the Dockerfile | | `labels` | List | | List of labels for an image (for `image` output) | | `output` | String | | Build output destination (one of [`image`](https://docs.docker.com/build/exporters/image-registry/) or [`local`](https://docs.docker.com/build/exporters/local-tar/)). Unlike the `build-push-action`, it only accepts `image` or `local`. The reusable workflow takes care of setting the `outputs` attribute | | `platforms` | List/CSV | | List of [target platforms](https://docs.docker.com/engine/reference/commandline/buildx_build/#platform) to build | | `push` | Bool | `false` | [Push](https://docs.docker.com/engine/reference/commandline/buildx_build/#push) image to the registry (for `image` output) | | `registry-identities` | YAML | | Keyless registry identity configuration. See [Registry identities](#registry-identities). | | `sbom` | Bool | `false` | Generate [SBOM](https://docs.docker.com/build/attestations/sbom/) attestation for the build | | `shm-size` | String | | Size of [`/dev/shm`](https://docs.docker.com/engine/reference/commandline/buildx_build/#shm-size) (e.g., `2g`) | | `sign` | String | `auto` | Sign attestation manifest for `image` output or artifacts for `local` output, can be one of `auto`, `true` or `false`. The `auto` mode will enable signing if `push` is enabled for pushing the `image` or if `artifact-upload` is enabled for uploading the `local` build output as GitHub Artifact | | `target` | String | | Sets the target stage to build | | `ulimit` | List | | [Ulimit](https://docs.docker.com/engine/reference/commandline/buildx_build/#ulimit) options (e.g., `nofile=1024:1024`) | | `set-meta-annotations` | Bool | `false` | Append OCI Image Format Specification annotations generated by `docker/metadata-action` | | `set-meta-labels` | Bool | `false` | Append OCI Image Format Specification labels generated by `docker/metadata-action` | | `meta-images` | List | | [List of images](https://github.com/docker/metadata-action?tab=readme-ov-file#images-input) to use as base name for tags (required for image output) | | `meta-tags` | List | | [List of tags](https://github.com/docker/metadata-action?tab=readme-ov-file#tags-input) as key-value pair attributes | | `meta-labels` | List | | [List of custom labels](https://github.com/docker/metadata-action?tab=readme-ov-file#overwrite-labels-and-annotations) | | `meta-annotations` | List | | [List of custom annotations](https://github.com/docker/metadata-action?tab=readme-ov-file#overwrite-labels-and-annotations) | | `meta-flavor` | List | | [Flavor](https://github.com/docker/metadata-action?tab=readme-ov-file#flavor-input) defines a global behavior for `meta-tags` | ### Secrets | Name | Default | Description | |------------------|-----------------------|--------------------------------------------------------------------------------| | `registry-auths` | | Raw authentication to registries, defined as YAML objects (for `image` output) | | `github-token` | `${{ github.token }}` | GitHub Token used to authenticate against the repository for Git context | ### Outputs These outputs are available as `needs..outputs.*` and can be passed directly to the [`verify.yml` reusable workflow](.github/workflows/verify.yml) with `builder-outputs: ${{ toJSON(needs..outputs) }}`. | Name | Type | Description | |--------------------------|--------|------------------------------------------------------------------------------| | `meta-json` | JSON | Metadata JSON output from `docker/metadata-action` (for `image` output) | | `cosign-version` | String | Cosign version used for verification | | `cosign-verify-commands` | List | Newline-delimited `cosign verify` commands generated when signing is enabled | | `artifact-name` | String | Name of the uploaded merged artifact (for `local` output) | | `digest` | String | Digest of the image pushed or artifact uploaded | | `output-type` | String | Output type selected for the workflow (`image` or `local`) | | `signed` | Bool | Whether attestation manifests or local artifacts were signed | ## Bake reusable workflow The [`bake.yml` reusable workflow](.github/workflows/bake.yml) lets you build container images and artifacts from a [Bake definition](https://docs.docker.com/build/bake/) with a user experience similar to [`docker/bake-action`](https://github.com/docker/bake-action/). It provides a Docker-maintained, opinionated build pipeline that applies best practices for security, performance, and reliability by default, including isolated execution and signed SLSA provenance while keeping per-repository configuration minimal. ```yaml name: ci permissions: contents: read on: push: branches: - 'main' tags: - 'v*' pull_request: jobs: bake: uses: docker/github-builder/.github/workflows/bake.yml@v1 permissions: contents: read # to fetch the repository content id-token: write # for signing attestations and cache entries with GitHub OIDC with: output: image push: ${{ github.event_name != 'pull_request' }} meta-images: name/app meta-tags: | type=ref,event=branch type=ref,event=pr type=semver,pattern={{version}} secrets: registry-auths: | - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} ``` ### Inputs > [!NOTE] > `List` type is a newline-delimited string > ```yaml > set: target.args.mybuildarg=value > ``` > ```yaml > set: | > target.args.mybuildarg=value > foo*.args.mybuildarg=value > ``` | Name | Type | Default | Description | |---------------------------|--------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `runner` | String | See [Runner mapping](#runner-mapping) | GitHub-hosted Linux runner label or platform mapping to build on. See [Runner mapping](#runner-mapping). | | `distribute` | Bool | `true` | Whether to distribute the build across multiple runners (one platform per runner) | | `fail-fast` | Bool | `false` | Whether to cancel all in-progress and queued jobs in the matrix if any job fails | | `job-name-prefix` | String | | Prefix to include in reusable workflow job matrix names in the GitHub Actions UI | | `setup-qemu` | Bool | `false` | Runs the `setup-qemu-action` step to install QEMU static binaries | | `artifact-name` | String | `docker-github-builder-assets` | Name of the uploaded GitHub artifact (for `local` output) | | `artifact-upload` | Bool | `false` | Upload build output GitHub artifact (for `local` output) | | `artifact-retention-days` | Number | `0` | Duration after which artifact will expire in days. `0` means using default retention | | `cache` | Bool | `false` | Enable [GitHub Actions cache](https://docs.docker.com/build/cache/backends/gha/) exporter | | `cache-scope` | String | target name or `buildkit` | Which [scope cache object belongs to](https://docs.docker.com/build/cache/backends/gha/#scope) if `cache` is enabled. This is the cache blob prefix name used when pushing cache to GitHub Actions cache backend | | `cache-mode` | String | `min` | [Cache layers to export](https://docs.docker.com/build/cache/backends/#cache-mode) if cache enabled (`min` or `max`). In `min` cache mode, only layers that are exported into the resulting image are cached, while in `max` cache mode, all layers are cached, even those of intermediate steps | | `context` | String | `.` | Context to build from in the Git working tree | | `files` | List | `{context}/docker-bake.hcl` | List of bake definition files | | `output` | String | | Build output destination (one of [`image`](https://docs.docker.com/build/exporters/image-registry/) or [`local`](https://docs.docker.com/build/exporters/local-tar/)). | | `push` | Bool | `false` | Push image to the registry (for `image` output) | | `registry-identities` | YAML | | Keyless registry identity configuration. See [Registry identities](#registry-identities). | | `sbom` | Bool | `false` | Generate [SBOM](https://docs.docker.com/build/attestations/sbom/) attestation for the build | | `set` | List | | List of [target values to override](https://docs.docker.com/engine/reference/commandline/buildx_bake/#set) (e.g., `targetpattern.key=value`) | | `sign` | String | `auto` | Sign attestation manifest for `image` output or artifacts for `local` output, can be one of `auto`, `true` or `false`. The `auto` mode will enable signing if `push` is enabled for pushing the `image` or if `artifact-upload` is enabled for uploading the `local` build output as GitHub Artifact | | `target` | String | `default` | Bake target to build | | `vars` | List | | [Variables](https://docs.docker.com/build/bake/variables/) to set in the Bake definition as list of key-value pair | | `set-meta-annotations` | Bool | `false` | Append OCI Image Format Specification annotations generated by `docker/metadata-action` | | `set-meta-labels` | Bool | `false` | Append OCI Image Format Specification labels generated by `docker/metadata-action` | | `meta-images` | List | | [List of images](https://github.com/docker/metadata-action?tab=readme-ov-file#images-input) to use as base name for tags (required for image output) | | `meta-tags` | List | | [List of tags](https://github.com/docker/metadata-action?tab=readme-ov-file#tags-input) as key-value pair attributes | | `meta-labels` | List | | [List of custom labels](https://github.com/docker/metadata-action?tab=readme-ov-file#overwrite-labels-and-annotations) | | `meta-annotations` | List | | [List of custom annotations](https://github.com/docker/metadata-action?tab=readme-ov-file#overwrite-labels-and-annotations) | | `meta-flavor` | List | | [Flavor](https://github.com/docker/metadata-action?tab=readme-ov-file#flavor-input) defines a global behavior for `meta-tags` | ### Secrets | Name | Default | Description | |------------------|-----------------------|--------------------------------------------------------------------------------| | `registry-auths` | | Raw authentication to registries, defined as YAML objects (for `image` output) | | `github-token` | `${{ github.token }}` | GitHub Token used to authenticate against the repository for Git context | ### Outputs These outputs are available as `needs..outputs.*` and can be passed directly to the [`verify.yml` reusable workflow](.github/workflows/verify.yml) with `builder-outputs: ${{ toJSON(needs..outputs) }}`. | Name | Type | Description | |--------------------------|--------|------------------------------------------------------------------------------| | `meta-json` | JSON | Metadata JSON output from `docker/metadata-action` (for `image` output) | | `cosign-version` | String | Cosign version used for verification | | `cosign-verify-commands` | List | Newline-delimited `cosign verify` commands generated when signing is enabled | | `artifact-name` | String | Name of the uploaded merged artifact (for `local` output) | | `digest` | String | Digest of the image pushed or artifact uploaded | | `output-type` | String | Output type selected for the workflow (`image` or `local`) | | `signed` | Bool | Whether attestation manifests or local artifacts were signed | ## Notes ### Signed GitHub Actions cache When the workflow has GitHub OIDC available through `id-token: write`, BuildKit signs cache entries with Cosign and requires restored cache entries to match the expected workflow identity and source repository policy before import. This verification matters because GitHub Actions cache is scoped to a repository, but repository writers can still create cache entries. For these reusable workflows, the Docker-owned workflow is the trusted build boundary. Without verification, a poisoned BuildKit cache could influence a later trusted build, which is the SLSA isolation concern described in [docker/github-builder#56](https://github.com/docker/github-builder/issues/56). ### Registry identities The `registry-identities` input configures keyless registry authentication from non-secret identity metadata. Do not put passwords, tokens, client secrets, private keys, raw cloud credential JSON, or other secret values in this input. When an image push or verification needs registry access, the workflow validates the YAML before any build work starts. `registry-identities` can be combined with the existing `registry-auths` secret. Provider-specific authentication steps are pinned in these reusable workflows; callers can only select supported provider types and pass identity configuration. The `build.yml`, `bake.yml`, and `verify.yml` reusable workflows accept this input. Use the same identity configuration with `verify.yml` when signature verification needs access to a private registry image. #### Docker Hub OIDC Docker Hub registry authentication can be configured with `type: dockerhub`. Callers must grant `id-token: write` so `docker/login-action` can exchange the GitHub OIDC token through the configured [Docker Hub OIDC connection](https://docs.docker.com/enterprise/security/oidc-connections/): ```yaml jobs: build: uses: docker/github-builder/.github/workflows/build.yml@v1 permissions: contents: read # to fetch the repository content id-token: write # for signing attestations, cache entries with GitHub OIDC and logging in to Docker Hub with: output: image push: ${{ github.event_name != 'pull_request' }} meta-images: | docker.io/my-organization/test-github-builder registry-identities: | - type: dockerhub username: my-organization connection_id: 123e4567-e89b-42d3-a456-426614174000 ``` | Name | Type | Required | Description | |-----------------|--------|----------|-----------------------------------------------------------------------------| | `type` | String | Yes | Registry identity provider type. Must be `dockerhub`. | | `registry` | String | No | Registry hostname passed to `docker/login-action`. Defaults to `docker.io`. | | `username` | String | Yes | Docker Hub username or organization passed to `docker/login-action`. | | `connection_id` | String | Yes | Docker Hub OIDC connection ID passed to `docker/login-action` in each job. | The workflow mints the Docker Hub access token inside each reusable workflow job that needs Docker Hub registry access. The token is not accepted as an input and is not passed across the reusable workflow boundary. If you call `verify.yml` for a private Docker Hub image, pass the same `registry-identities` value to that workflow instead of using a Docker Hub PAT. #### AWS ECR Amazon ECR registry authentication is configured with `type: aws-ecr`. Callers must grant `id-token: write` so the AWS credential step can assume the role through GitHub OIDC: ```yaml jobs: build: uses: docker/github-builder/.github/workflows/build.yml@v1 permissions: contents: read # to fetch the repository content id-token: write # for signing attestations, cache entries with GitHub OIDC and log in to AWS ECR with: output: image push: ${{ github.event_name != 'pull_request' }} meta-images: | 123456789100.dkr.ecr.us-east-1.amazonaws.com/sandbox/test-github-builder registry-identities: | - type: aws-ecr registry: 123456789100.dkr.ecr.us-east-1.amazonaws.com role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role region: us-east-1 ``` | Name | Type | Required | Description | |------------------|--------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `type` | String | Yes | Registry identity provider type. Must be `aws-ecr`. | | `registry` | String | Yes | Registry server passed to `docker/login-action`, such as `public.ecr.aws` for public ECR or a private ECR host for private ECR. | | `role-to-assume` | String | Yes | IAM role ARN assumed through GitHub OIDC. | | `region` | String | Yes | AWS region passed to `aws-actions/configure-aws-credentials` when assuming the role. Use `us-east-1` for ECR Public. | The `registry` value is required for AWS ECR. Use the registry server that `docker/login-action` should log in to, such as `public.ecr.aws` for public ECR or `123456789100.dkr.ecr.us-east-1.amazonaws.com` for private ECR. #### Google Artifact Registry Google Artifact Registry authentication is configured with `type: gcp-wif`. Callers must grant `id-token: write` so `google-github-actions/auth` can exchange the GitHub OIDC token through GCP Workload Identity Federation: ```yaml jobs: build: uses: docker/github-builder/.github/workflows/build.yml@v1 permissions: contents: read # to fetch the repository content id-token: write # for signing attestations, cache entries with GitHub OIDC and log in to Google Artifact Registry with: output: image push: ${{ github.event_name != 'pull_request' }} meta-images: | us-docker.pkg.dev/my-project/sandbox/test-github-builder registry-identities: | - type: gcp-wif registry: us-docker.pkg.dev workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github/providers/provider service_account: builder@my-project.iam.gserviceaccount.com project_id: my-project ``` | Name | Type | Required | Description | |------------------------------|--------|----------|------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | String | Yes | Registry identity provider type. Must be `gcp-wif`. | | `registry` | String | Yes | Google Artifact Registry host passed to `docker/login-action`, such as `us-docker.pkg.dev`. Do not use the full repository path. | | `workload_identity_provider` | String | Yes | Workload Identity Provider resource name passed to `google-github-actions/auth`. | | `service_account` | String | Yes | Service account email passed to `google-github-actions/auth` for Workload Identity Federation. | | `project_id` | String | No | Google Cloud project ID passed to `google-github-actions/auth` when provided. | The `registry` value is required for GCP WIF. Use the Artifact Registry host that `docker/login-action` should log in to, such as `us-docker.pkg.dev`, not the full repository path. The workflow requests an access token from `google-github-actions/auth` and passes it directly to `docker/login-action` with the `oauth2accesstoken` username inside the same job. ### Runner mapping The `runner` input accepts either a single GitHub-hosted Linux runner label or a newline-delimited platform mapping. A single label is used for every build: ```yaml runner: ubuntu-24.04 ``` The default value uses the standard GitHub-hosted Ubuntu runners: ```yaml runner: | default=ubuntu-24.04 linux/arm=ubuntu-24.04-arm linux/arm64=ubuntu-24.04-arm ``` A mapping must define a `default` runner. Additional keys are platform prefixes, and the most specific matching prefix wins. For example: ```yaml runner: | default=ubuntu-24.04 linux=ubuntu-24.04 linux/arm=ubuntu-24.04-arm ``` For example, `linux` matches all Linux platforms, `linux/arm` matches variants such as `linux/arm/v7`, and `linux/arm64` is separate from `linux/arm`. ### Metadata templates When `output=image`, some inputs support Handlebars templates rendered from selected `docker/metadata-action` outputs. The template context is exposed as `meta` with `meta.version` and `meta.tags`. For the build workflow, the `annotations`, `build-args`, and `labels` inputs support metadata templates: ```yaml jobs: build: uses: docker/github-builder/.github/workflows/build.yml@v1 with: output: image build-args: | VERSION={{meta.version}} meta-images: name/app ``` For the bake workflow, the `set` input supports metadata templates: ```yaml jobs: bake: uses: docker/github-builder/.github/workflows/bake.yml@v1 with: output: image set: | *.args.VERSION={{meta.version}} meta-images: name/app ``` > [!NOTE] > The `meta-labels` and `meta-annotations` inputs are passed to > `docker/metadata-action`, so their templates follow `docker/metadata-action` > behavior. Enable `set-meta-labels` or `set-meta-annotations` to apply those > generated values to the image. In the build workflow, generated values are > appended to any `labels` or `annotations` already set.