From 3696bbfdcd5b57ec2ac037e7540a9b5509a693f8 Mon Sep 17 00:00:00 2001 From: CrazyMax <1951866+crazy-max@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:10:25 +0100 Subject: [PATCH] readme: key advantages Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- README.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 140 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index ec99041..ce8d62e 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,149 @@ +[![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) + > [!CAUTION] > Do not use it for your production workflows yet! -# GitHub Builder - -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 using Docker best practices. The workflows -sign BuildKit-generated SLSA-compliant provenance attestations and align with -the principles behind [Docker Hardened Images](https://docs.docker.com/dhi/), -enabling open source projects to follow a seamless path toward higher levels of -security and trust. - ## :test_tube: Experimental This repository is considered **EXPERIMENTAL** and under active development until further notice. It is subject to non-backward compatible changes or removal in any future version. -## Build reusable workflow +___ + +* [Overview](#overview) +* [Key Advantages](#key-advantages) + * [Performance](#performance) + * [Security](#security) + * [Isolation & Reliability](#isolation--reliability) +* [Usage](#usage) + * [Build reusable workflow](#build-reusable-workflow) + * [Bake reusable workflow](#bake-reusable-workflow) + +## 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 +`build-push-action`, `login-action`, `metadata-action`, etc., into a single +workflow: + +```yaml +name: ci + +permissions: + contents: read + +on: + push: + branches: + - 'main' + tags: + - 'v*' + pull_request: + + build: + uses: docker/github-builder-experimental/.github/workflows/build.yml@main + 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' }} + 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, even for external + contributors' pull requests. + +* **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. + +### 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. + +## Usage + +### Build reusable workflow ```yaml name: ci @@ -36,7 +163,7 @@ on: uses: docker/github-builder-experimental/.github/workflows/build.yml@main permissions: contents: read # to fetch the repository content - id-token: write # for signing attestation manifests with GitHub OIDC Token + id-token: write # for signing attestation(s) with GitHub OIDC Token with: output: image push: ${{ github.event_name != 'pull_request' }} @@ -71,7 +198,7 @@ on: You can find the list of available inputs in [`.github/workflows/build.yml`](.github/workflows/build.yml). -## Bake reusable workflow +### Bake reusable workflow ```yaml name: ci @@ -91,7 +218,7 @@ on: uses: docker/github-builder-experimental/.github/workflows/bake.yml@main permissions: contents: read # to fetch the repository content - id-token: write # for signing attestation manifests with GitHub OIDC Token + id-token: write # for signing attestation(s) with GitHub OIDC Token with: output: image push: ${{ github.event_name != 'pull_request' }}