Skip to content

Commit cfe318e

Browse files
crazy-maxcrazy-max
authored
Merge pull request #24361 from crazy-max/github-builder
docker github builder docs
2 parents b71533f + e90615a commit cfe318e

5 files changed

Lines changed: 458 additions & 242 deletions

File tree

‎content/manuals/build/ci/github-actions/github-builder/_index.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
title: Docker GitHub Builder
3+
linkTitle: GitHub Builder
4+
description: Use Docker-maintained reusable GitHub Actions workflows to build images and artifacts with BuildKit.
5+
keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows
6+
params:
7+
sidebar:
8+
badge:
9+
color: green
10+
text: New
11+
---
12+
13+
Docker GitHub Builder is a set of [reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
14+
in the [`docker/github-builder` repository](https://github.com/docker/github-builder)
15+
for building container images and local artifacts with [BuildKit](../../../buildkit/_index.md).
16+
This section explains what the workflows solve, how they differ from wiring
17+
together individual GitHub Actions in each repository, and when to use
18+
[`build.yml`](build.md) or [`bake.yml`](bake.md).
19+
20+
If you compose a build job from `docker/login-action`, `docker/setup-buildx-action`,
21+
`docker/metadata-action`, and either `docker/build-push-action` or
22+
`docker/bake-action`, your repository owns every detail of how the build runs.
23+
That approach works, but it also means every repository has to maintain its own
24+
runner selection, [cache setup](../cache.md), [Provenance settings](../attestations.md),
25+
signing behavior, and [multi-platform manifest handling](../multi-platform.md).
26+
Docker GitHub Builder moves that implementation into Docker-maintained reusable
27+
workflows, so your workflow only decides when to build and which inputs to pass.
28+
29+
The difference is easiest to see in the job definition. A conventional workflow
30+
spells out each action step:
31+
32+
```yaml
33+
jobs:
34+
docker:
35+
runs-on: ubuntu-latest
36+
steps:
37+
- name: Login to Docker Hub
38+
uses: docker/login-action@{{% param "login_action_version" %}}
39+
with:
40+
username: ${{ vars.DOCKERHUB_USERNAME }}
41+
password: ${{ secrets.DOCKERHUB_TOKEN }}
42+
43+
- name: Set up QEMU
44+
uses: docker/setup-qemu-action@{{% param "setup_qemu_action_version" %}}
45+
46+
- name: Set up Docker Buildx
47+
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
48+
49+
- name: Docker meta
50+
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
51+
id: meta
52+
with:
53+
images: name/app
54+
55+
- name: Build and push
56+
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
57+
with:
58+
push: ${{ github.event_name != 'pull_request' }}
59+
tags: ${{ steps.meta.outputs.tags }}
60+
labels: ${{ steps.meta.outputs.labels }}
61+
cache-from: type=gha
62+
cache-to: type=gha
63+
```
64+
65+
With Docker GitHub Builder, the same build is a reusable workflow call:
66+
67+
```yaml
68+
jobs:
69+
build:
70+
uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}}
71+
permissions:
72+
contents: read # to fetch the repository content
73+
id-token: write # for signing attestation(s) with GitHub OIDC Token
74+
with:
75+
output: image
76+
push: ${{ github.event_name != 'pull_request' }}
77+
meta-images: name/app
78+
secrets:
79+
registry-auths: |
80+
- registry: docker.io
81+
username: ${{ vars.DOCKERHUB_USERNAME }}
82+
password: ${{ secrets.DOCKERHUB_TOKEN }}
83+
```
84+
85+
This model gives you a build pipeline that is maintained in the Docker
86+
organization, uses a pinned [BuildKit](../../../buildkit/_index.md) environment,
87+
distributes [multi-platform builds](../../../building/multi-platform.md) across
88+
runners when that helps, and emits signed [SLSA provenance](../../../metadata/attestations/slsa-provenance.md)
89+
that records both the source commit and the builder identity.
90+
91+
That tradeoff is intentional. You keep control of when the build runs and which
92+
inputs it uses, but the build implementation itself lives in the
93+
Docker-maintained workflow rather than in per-repository job steps.
94+
95+
Use [`build.yml`](build.md) when your repository builds from a Dockerfile and
96+
the familiar `build-push-action` inputs map cleanly to your workflow. Use
97+
[`bake.yml`](bake.md) when your repository already describes builds in a
98+
[Bake definition](../../../bake/_index.md), or when you want Bake targets,
99+
overrides, and variables to stay as the source of truth.
100+
101+
Both workflows support image output, local output, cache export to the
102+
[GitHub Actions cache backend](../../../cache/backends/gha.md),
103+
[SBOM generation](../../../metadata/attestations/sbom.md), and signing. The
104+
Bake workflow adds Bake definition validation and builds one target per workflow
105+
call.
106+
107+
{{% sectionlinks %}}

‎content/manuals/build/ci/github-actions/github-builder/bake.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Bake with Docker GitHub Builder
3+
linkTitle: Bake
4+
description: Use the Docker GitHub Builder bake.yml reusable workflow to build images and local artifacts from a Bake definition.
5+
keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflow
6+
weight: 20
7+
---
8+
9+
The [`bake.yml` reusable workflow](https://github.com/docker/github-builder?tab=readme-ov-file#bake-reusable-workflow)
10+
builds from a [Bake definition](../../../bake/_index.md) instead of a Dockerfile
11+
input set. This page shows how to call the workflow for a target, how to pass
12+
Bake overrides and variables, and how to export local output when a Bake file
13+
is already the source of truth for your build.
14+
15+
## Build and push a Bake target
16+
17+
The following workflow builds the `image` target from `docker-bake.hcl` and
18+
publishes the result with tags generated from [metadata inputs](../manage-tags-labels.md):
19+
20+
```yaml
21+
name: ci
22+
23+
on:
24+
push:
25+
branches:
26+
- "main"
27+
tags:
28+
- "v*"
29+
pull_request:
30+
31+
permissions:
32+
contents: read
33+
34+
jobs:
35+
bake:
36+
uses: docker/github-builder/.github/workflows/bake.yml@{{% param "github_builder_version" %}}
37+
permissions:
38+
contents: read # to fetch the repository content
39+
id-token: write # for signing attestation(s) with GitHub OIDC Token
40+
with:
41+
output: image
42+
push: ${{ github.event_name != 'pull_request' }}
43+
target: image
44+
meta-images: name/app
45+
meta-tags: |
46+
type=ref,event=branch
47+
type=ref,event=pr
48+
type=semver,pattern={{version}}
49+
secrets:
50+
registry-auths: |
51+
- registry: docker.io
52+
username: ${{ vars.DOCKERHUB_USERNAME }}
53+
password: ${{ secrets.DOCKERHUB_TOKEN }}
54+
```
55+
56+
Bake workflows build one target per workflow call. Groups and multi-target
57+
builds aren't supported because [SLSA provenance](../attestations.md), digest
58+
handling, and manifest creation are scoped to a single target.
59+
60+
The workflow validates the definition before the build starts and resolves
61+
the target from the files you pass in `files`.
62+
63+
## Override target values and variables
64+
65+
Because the workflow delegates the build to Bake, you can keep using `set` and
66+
`vars` for target-specific overrides:
67+
68+
```yaml
69+
name: ci
70+
71+
on:
72+
push:
73+
branches:
74+
- "main"
75+
76+
permissions:
77+
contents: read
78+
79+
jobs:
80+
bake:
81+
uses: docker/github-builder/.github/workflows/bake.yml@{{% param "github_builder_version" %}}
82+
permissions:
83+
contents: read # to fetch the repository content
84+
id-token: write # for signing attestation(s) with GitHub OIDC Token
85+
with:
86+
output: image
87+
push: true
88+
target: image
89+
vars: |
90+
IMAGE_TAG=${{ github.sha }}
91+
set: |
92+
*.args.BUILD_RUN_ID=${{ github.run_id }}
93+
*.platform=linux/amd64,linux/arm64
94+
cache: true
95+
cache-scope: image
96+
meta-images: name/app
97+
meta-tags: |
98+
type=sha
99+
set-meta-annotations: true
100+
secrets:
101+
registry-auths: |
102+
- registry: docker.io
103+
username: ${{ vars.DOCKERHUB_USERNAME }}
104+
password: ${{ secrets.DOCKERHUB_TOKEN }}
105+
```
106+
107+
This form fits repositories that already use Bake groups, target inheritance,
108+
and variable expansion. The reusable workflow takes care of Buildx setup,
109+
[GitHub Actions cache export](../../../cache/backends/gha.md),
110+
[Provenance defaults](../../../metadata/attestations/slsa-provenance.md),
111+
signing behavior, and the final multi-platform manifest. Metadata labels and
112+
annotations can be merged into the Bake definition without adding a separate
113+
metadata step to your workflow.
114+
115+
## Export local output from Bake
116+
117+
If the target should export files instead of publishing an image, switch the
118+
workflow output to `local` and upload the artifact:
119+
120+
```yaml
121+
name: ci
122+
123+
on:
124+
pull_request:
125+
126+
permissions:
127+
contents: read
128+
129+
jobs:
130+
bake:
131+
uses: docker/github-builder/.github/workflows/bake.yml@{{% param "github_builder_version" %}}
132+
permissions:
133+
contents: read # to fetch the repository content
134+
id-token: write # for signing attestation(s) with GitHub OIDC Token
135+
with:
136+
output: local
137+
target: binaries
138+
artifact-upload: true
139+
artifact-name: bake-output
140+
```
141+
142+
With `output: local`, the workflow injects the matching local output override
143+
into the Bake run and merges the uploaded artifacts after the per-platform
144+
builds finish. If you need a manual Bake pattern that stays in a normal job,
145+
see [Multi-platform image](../multi-platform.md). If your build does not need a
146+
Bake definition, use [build.yml](build.md) instead.

0 commit comments

Comments
 (0)