Skip to content

Commit 3696bbf

Browse files
crazy-maxcrazy-max
committed
readme: key advantages
Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>
1 parent 4358d19 commit 3696bbf

File tree

1 file changed

+140
-13
lines changed

1 file changed

+140
-13
lines changed

‎README.md‎

Lines changed: 140 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,149 @@
1+
[![Test workflow](https://img.shields.io/github/actions/workflow/status/docker/github-builder-experimental/.test.yml?label=test&logo=github&style=flat-square)](https://github.com/docker/github-builder-experimental/actions?workflow=.test)
2+
13
> [!CAUTION]
24
> Do not use it for your production workflows yet!
35
4-
# GitHub Builder
5-
6-
This repository provides official Docker-maintained [reusable GitHub Actions workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
7-
to securely build container images using Docker best practices. The workflows
8-
sign BuildKit-generated SLSA-compliant provenance attestations and align with
9-
the principles behind [Docker Hardened Images](https://docs.docker.com/dhi/),
10-
enabling open source projects to follow a seamless path toward higher levels of
11-
security and trust.
12-
136
## :test_tube: Experimental
147

158
This repository is considered **EXPERIMENTAL** and under active development
169
until further notice. It is subject to non-backward compatible changes or
1710
removal in any future version.
1811

19-
## Build reusable workflow
12+
___
13+
14+
* [Overview](#overview)
15+
* [Key Advantages](#key-advantages)
16+
* [Performance](#performance)
17+
* [Security](#security)
18+
* [Isolation & Reliability](#isolation--reliability)
19+
* [Usage](#usage)
20+
* [Build reusable workflow](#build-reusable-workflow)
21+
* [Bake reusable workflow](#bake-reusable-workflow)
22+
23+
## Overview
24+
25+
This repository provides official Docker-maintained [reusable GitHub Actions workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
26+
to securely build container images and artifacts using Docker best practices.
27+
The reusable workflows incorporate functionality from our GitHub Actions like
28+
`build-push-action`, `login-action`, `metadata-action`, etc., into a single
29+
workflow:
30+
31+
```yaml
32+
name: ci
33+
34+
permissions:
35+
contents: read
36+
37+
on:
38+
push:
39+
branches:
40+
- 'main'
41+
tags:
42+
- 'v*'
43+
pull_request:
44+
45+
build:
46+
uses: docker/github-builder-experimental/.github/workflows/build.yml@main
47+
permissions:
48+
contents: read # to fetch the repository content
49+
id-token: write # for signing attestation(s) with GitHub OIDC Token
50+
with:
51+
output: image
52+
push: ${{ github.event_name != 'pull_request' }}
53+
meta-images: name/app
54+
secrets:
55+
registry-auths: |
56+
- registry: docker.io
57+
username: ${{ vars.DOCKERHUB_USERNAME }}
58+
password: ${{ secrets.DOCKERHUB_TOKEN }}
59+
```
60+
61+
This workflow provides a trusted BuildKit instance and generates signed
62+
SLSA-compliant provenance attestations, guaranteeing the build happened from
63+
the source commit and all build steps ran in isolated sandboxed environments
64+
from immutable sources. This enables GitHub projects to follow a seamless path
65+
toward higher levels of security and trust.
66+
67+
## Key Advantages
68+
69+
### Performance
70+
71+
* **Native parallelization for multi-platform builds.**
72+
Workflows can automatically distribute builds across runners based on target
73+
platform to be built, improving throughput for other architectures without
74+
requiring emulation or [custom CI logic](https://docs.docker.com/build/ci/github-actions/multi-platform/#distribute-build-across-multiple-runners)
75+
or self-managed runners.
76+
77+
* **Optimized cache warming & reuse.**
78+
The builder can use the GitHub Actions cache backend to persist layers across
79+
branches, PRs, and rebuilds. This significantly reduces cold-start times and
80+
avoids repeating expensive dependency installations, even for external
81+
contributors' pull requests.
82+
83+
* **Centralized build configuration.**
84+
Repositories no longer need to configure buildx drivers, tune storage, or
85+
adjust resource limits. The reusable workflows encapsulate the recommended
86+
configuration, providing fast, consistent builds across any project that
87+
opts in.
88+
89+
### Security
90+
91+
* **Trusted workflows in the Docker organization.**
92+
Builds are executed by reusable workflows defined in the [**@docker**](https://github.com/docker)
93+
organization, not by arbitrary user-defined workflow steps. Consumers can
94+
rely on GitHub's trust model and repository protections on the Docker side
95+
(branch protection, code review, signing, etc.) to reason about who controls
96+
the build logic.
97+
98+
* **Verifiable, immutable sources.**
99+
The workflows use the GitHub OIDC token and the exact commit SHA to obtain
100+
source and to bind it into SLSA provenance. This ensures that the build is
101+
tied to the repository contents as checked in—no additional CI step can
102+
silently swap out what is being built.
103+
104+
* **Signed SLSA provenance for every build.**
105+
BuildKit generates [SLSA-compliant provenance attestation](https://docs.docker.com/build/metadata/attestations/slsa-provenance/)
106+
artifacts that are signed with an identity bound to the GitHub workflow.
107+
Downstream consumers can verify:
108+
- which builder commit produced the image
109+
- which source code commit produced the image
110+
- which workflow and job executed the build
111+
- what inputs and build parameters were used
112+
113+
* **Protection from user workflow tampering.**
114+
The build steps are pre-defined and optimized in the reusable workflow, and
115+
cannot be altered by user configuration. This protects against tampering:
116+
preventing untrusted workflow steps from modifying build logic, injecting
117+
unexpected flags, or producing misleading provenance.
118+
119+
### Isolation & Reliability
120+
121+
* **Separation between user CI logic and build logic.**
122+
The user's workflow orchestrates *when* to build but not *how* to build.
123+
The actual build steps live in the Docker-maintained reusable workflows,
124+
which cannot be modified from the consuming repository.
125+
126+
* **Immutable, reproducible build pipeline.**
127+
Builds are driven by declarative inputs (repository commit, build
128+
configuration, workflow version). This leads to:
129+
- reproducibility (same workflow + same inputs → same outputs)
130+
- auditability (inputs and workflow identity recorded in provenance)
131+
- reliability (less dependence on ad-hoc per-repo CI scripting)
132+
133+
* **Reduced CI variability and config drift.**
134+
By reusing the same workflows, projects avoid maintaining custom build logic
135+
per repository. Caching, provenance, SBOM generation, and build settings
136+
behave uniformly across all adopters.
137+
138+
* **Higher assurance for downstream consumers.**
139+
Because artifacts are produced by a workflow in the [**@docker**](https://github.com/docker)
140+
organization, with SLSA provenance attached, consumers can verify both the
141+
*source commit* and the *builder identity* before trusting or promoting an
142+
image, an essential part of supply-chain hardening.
143+
144+
## Usage
145+
146+
### Build reusable workflow
20147
21148
```yaml
22149
name: ci
@@ -36,7 +163,7 @@ on:
36163
uses: docker/github-builder-experimental/.github/workflows/build.yml@main
37164
permissions:
38165
contents: read # to fetch the repository content
39-
id-token: write # for signing attestation manifests with GitHub OIDC Token
166+
id-token: write # for signing attestation(s) with GitHub OIDC Token
40167
with:
41168
output: image
42169
push: ${{ github.event_name != 'pull_request' }}
@@ -71,7 +198,7 @@ on:
71198
72199
You can find the list of available inputs in [`.github/workflows/build.yml`](.github/workflows/build.yml).
73200

74-
## Bake reusable workflow
201+
### Bake reusable workflow
75202

76203
```yaml
77204
name: ci
@@ -91,7 +218,7 @@ on:
91218
uses: docker/github-builder-experimental/.github/workflows/bake.yml@main
92219
permissions:
93220
contents: read # to fetch the repository content
94-
id-token: write # for signing attestation manifests with GitHub OIDC Token
221+
id-token: write # for signing attestation(s) with GitHub OIDC Token
95222
with:
96223
output: image
97224
push: ${{ github.event_name != 'pull_request' }}

0 commit comments

Comments
 (0)