diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md index 50712cb99dec..178b7d5f4617 100644 --- a/content/manuals/build/ci/github-actions/_index.md +++ b/content/manuals/build/ci/github-actions/_index.md @@ -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 builds from the repository at the triggering Git reference. +Files changed in a caller job aren't included in 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. diff --git a/content/manuals/build/ci/github-actions/annotations.md b/content/manuals/build/ci/github-actions/annotations.md index 6faee4ab38d6..05352e43ad93 100644 --- a/content/manuals/build/ci/github-actions/annotations.md +++ b/content/manuals/build/ci/github-actions/annotations.md @@ -8,6 +8,42 @@ 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. Use `meta-annotations` to override generated values while preserving +the other metadata. This example adds a custom 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 + meta-annotations: | + 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 +113,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 +138,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 +167,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" %}} diff --git a/content/manuals/build/ci/github-actions/attestations.md b/content/manuals/build/ci/github-actions/attestations.md index 75a1c822b72e..22f251c0f326 100644 --- a/content/manuals/build/ci/github-actions/attestations.md +++ b/content/manuals/build/ci/github-actions/attestations.md @@ -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" %}} diff --git a/content/manuals/build/ci/github-actions/github-builder/bake.md b/content/manuals/build/ci/github-actions/bake-workflow.md similarity index 85% rename from content/manuals/build/ci/github-actions/github-builder/bake.md rename to content/manuals/build/ci/github-actions/bake-workflow.md index c40d4a6314c4..191837e7f048 100644 --- a/content/manuals/build/ci/github-actions/github-builder/bake.md +++ b/content/manuals/build/ci/github-actions/bake-workflow.md @@ -3,11 +3,13 @@ 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. @@ -15,7 +17,7 @@ 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. diff --git a/content/manuals/build/ci/github-actions/github-builder/build.md b/content/manuals/build/ci/github-actions/build-workflow.md similarity index 83% rename from content/manuals/build/ci/github-actions/github-builder/build.md rename to content/manuals/build/ci/github-actions/build-workflow.md index 46f15d37ee21..789023557327 100644 --- a/content/manuals/build/ci/github-actions/github-builder/build.md +++ b/content/manuals/build/ci/github-actions/build-workflow.md @@ -3,13 +3,15 @@ title: Build with Docker GitHub Builder linkTitle: Build workflow description: Use the Docker GitHub Builder build.yml reusable workflow to build images and local artifacts from a Dockerfile. keywords: ci, github actions, gha, buildkit, buildx, reusable workflow, dockerfile -weight: 20 +aliases: + - /build/ci/github-actions/github-builder/build/ +weight: 10 --- The [`build.yml` reusable workflow](https://github.com/docker/github-builder?tab=readme-ov-file#build-reusable-workflow) builds from a Dockerfile and packages the same core tasks that many repositories wire together by hand. This page shows how to call the workflow, publish -[multi-platform images](../../../building/multi-platform.md), and export local +[multi-platform images](../../building/multi-platform.md), and export local build artifacts without rebuilding the job structure in every repository. ## Build and push an image @@ -54,14 +56,14 @@ jobs: ``` When you set `output: image`, `meta-images` is required because the workflow -creates image names and [manifest tags](../manage-tags-labels.md) from that +creates image names and [manifest tags](manage-tags-labels.md) from that input. `distribute: true` is the default, so a multi-platform build can fan out across native GitHub-hosted runners instead of forcing the whole build onto one -machine. The default `runner` mapping sends Linux Arm platforms to -`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To change that -mapping, see [runner selection](architecture.md#runner-selection). `sign: auto` +machine. For the default `runner` mapping, see +[Runner mapping](https://github.com/docker/github-builder#runner-mapping). To change +that mapping, see [runner selection](github-builder-architecture/index.md#runner-selection). `sign: auto` is also the default, which means the workflow signs -[attestation manifests](../attestations.md) when the image is pushed. +[attestation manifests](attestations.md) when the image is pushed. ## Export local output as an artifact @@ -144,9 +146,9 @@ jobs: This is a Dockerfile build, so the inputs map closely to `docker/build-push-action`. The difference is that the reusable workflow owns -Buildx setup, [BuildKit](../../../buildkit/_index.md) configuration, -[SLSA provenance](../../../metadata/attestations/slsa-provenance.md) mode, -[GitHub Actions cache backend](../../../cache/backends/gha.md) wiring, signing, +Buildx setup, [BuildKit](../../buildkit/_index.md) configuration, +[SLSA provenance](../../metadata/attestations/slsa-provenance.md) mode, +[GitHub Actions cache backend](../../cache/backends/gha.md) wiring, signing, and manifest creation. If you need more background on metadata or platform -distribution, see [Manage tags and labels](../manage-tags-labels.md) and -[Multi-platform image](../multi-platform.md). +distribution, see [Manage tags and labels](manage-tags-labels.md) and +[Multi-platform image](multi-platform.md). diff --git a/content/manuals/build/ci/github-actions/cache.md b/content/manuals/build/ci/github-actions/cache.md index 4b30d2d175cc..797b102c9553 100644 --- a/content/manuals/build/ci/github-actions/cache.md +++ b/content/manuals/build/ci/github-actions/cache.md @@ -5,53 +5,24 @@ linkTitle: Cache management keywords: ci, github actions, gha, buildkit, buildx, cache --- -This page contains examples on using the cache storage backends with GitHub -Actions. +Use Docker GitHub Builder with the GitHub Actions cache backend for reusable +build workflows. The individual-action examples cover other cache backends +and cache mounts. > [!NOTE] > > See [Cache storage backends](../../cache/backends/_index.md) for more > details about cache storage backends. -## Inline cache - -In most cases you want to use the [inline cache exporter](../../cache/backends/inline.md). -However, note that the `inline` cache exporter only supports `min` cache mode. -To use `max` cache mode, push the image and the cache separately using the -registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache). - -```yaml -name: ci - -on: - push: - -jobs: - docker: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: true - tags: user/app:latest - cache-from: type=registry,ref=user/app:latest - cache-to: type=inline -``` +## GitHub cache -## Registry cache +### Enable cache with GitHub Builder {#enable-cache-with-builder} -You can import/export cache from a cache manifest or (special) image -configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md). +[Docker GitHub Builder](build-workflow.md) disables caching by default. +Set `cache: true` to import and export GitHub Actions cache. Set +`cache-mode: max` to export intermediate layers, and use `cache-scope` to +separate builds for different images. GitHub Builder adds the platform to the scope +for distributed builds and makes cache export failures non-fatal. ```yaml name: ci @@ -60,31 +31,34 @@ on: push: jobs: - docker: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: + build: + uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}} + permissions: + contents: read + id-token: write + with: + output: image + push: true + cache: true + cache-mode: max + cache-scope: app + meta-images: user/app + secrets: + registry-auths: | + - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: true - tags: user/app:latest - cache-from: type=registry,ref=user/app:buildcache - cache-to: type=registry,ref=user/app:buildcache,mode=max ``` -## GitHub cache +The same cache inputs are available with the [Bake workflow](bake-workflow.md). +See [cache write restrictions](#cache-write-restrictions) for event restrictions. +GitHub Builder's `cache-mode` input selects the layers to export (`min` or `max`); +it doesn't grant cache write access. ### Cache backend API +The following examples configure the backend with individual actions. + {{< summary-bar feature_name="Cache backend API" >}} The [GitHub Actions cache exporter](../../cache/backends/gha.md) @@ -355,3 +329,71 @@ jobs: cache-from: type=local,src=${{ runner.temp }}/.buildx-cache cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache,mode=max,reset=true ``` + +## Inline cache + +Use individual actions for the [inline cache exporter](../../cache/backends/inline.md). +However, note that the `inline` cache exporter only supports `min` cache mode. +To use `max` cache mode, push the image and the cache separately using the +registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache). + +```yaml +name: ci + +on: + push: + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Login to Docker Hub + uses: docker/login-action@{{% param "login_action_version" %}} + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} + + - name: Build and push + uses: docker/build-push-action@{{% param "build_push_action_version" %}} + with: + push: true + tags: user/app:latest + cache-from: type=registry,ref=user/app:latest + cache-to: type=inline +``` + +## Registry cache + +You can import/export cache from a cache manifest or (special) image +configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md). + +```yaml +name: ci + +on: + push: + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Login to Docker Hub + uses: docker/login-action@{{% param "login_action_version" %}} + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} + + - name: Build and push + uses: docker/build-push-action@{{% param "build_push_action_version" %}} + with: + push: true + tags: user/app:latest + cache-from: type=registry,ref=user/app:buildcache + cache-to: type=registry,ref=user/app:buildcache,mode=max +``` diff --git a/content/manuals/build/ci/github-actions/github-builder/images/architecture-overview.png b/content/manuals/build/ci/github-actions/github-builder-architecture/images/architecture-overview.png similarity index 100% rename from content/manuals/build/ci/github-actions/github-builder/images/architecture-overview.png rename to content/manuals/build/ci/github-actions/github-builder-architecture/images/architecture-overview.png diff --git a/content/manuals/build/ci/github-actions/github-builder/images/execution-flow.png b/content/manuals/build/ci/github-actions/github-builder-architecture/images/execution-flow.png similarity index 100% rename from content/manuals/build/ci/github-actions/github-builder/images/execution-flow.png rename to content/manuals/build/ci/github-actions/github-builder-architecture/images/execution-flow.png diff --git a/content/manuals/build/ci/github-actions/github-builder/architecture.md b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md similarity index 91% rename from content/manuals/build/ci/github-actions/github-builder/architecture.md rename to content/manuals/build/ci/github-actions/github-builder-architecture/index.md index bcb3bddda746..c7f3aebca6f6 100644 --- a/content/manuals/build/ci/github-actions/github-builder/architecture.md +++ b/content/manuals/build/ci/github-actions/github-builder-architecture/index.md @@ -1,9 +1,11 @@ --- title: Docker GitHub Builder architecture -linkTitle: Architecture +linkTitle: GitHub Builder architecture description: Learn about the architecture of Docker GitHub Builder, a set of reusable workflows for building images and artifacts with BuildKit in GitHub Actions. keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows -weight: 10 +aliases: + - /build/ci/github-actions/github-builder/architecture/ +weight: 30 --- Docker GitHub Builder separates repository orchestration from build @@ -18,9 +20,9 @@ signing, and multi-platform assembly in one Docker-maintained path. ## Core architecture -A caller workflow invokes either [`build.yml`](build.md) or [`bake.yml`](bake.md). -[`build.yml`](build.md) is the entrypoint for Dockerfile-oriented builds. -[`bake.yml`](bake.md) is the entrypoint for Bake-oriented builds, where the +A caller workflow invokes either [`build.yml`](../build-workflow.md) or [`bake.yml`](../bake-workflow.md). +[`build.yml`](../build-workflow.md) is the entrypoint for Dockerfile-oriented builds. +[`bake.yml`](../bake-workflow.md) is the entrypoint for Bake-oriented builds, where the Bake definition remains the source of truth for targets and overrides. In both cases the caller still owns repository policy, including triggers, branch conditions, permissions, secrets, target selection, metadata inputs, and the @@ -47,14 +49,8 @@ conceptual platform jobs: The `runner` input accepts either a single GitHub-hosted Linux runner label or a newline-delimited platform mapping. -The default value is a platform mapping that uses GitHub-hosted Ubuntu runners: - -```yaml -runner: | - default=ubuntu-24.04 - linux/arm=ubuntu-24.04-arm - linux/arm64=ubuntu-24.04-arm -``` +For the default mapping, see +[Runner mapping](https://github.com/docker/github-builder#runner-mapping). In the platform job, the runner label resolves to a single value: @@ -96,13 +92,13 @@ BuildKit, caching, or manifest assembly were wired together. ## The two reusable entrypoints -[`build.yml`](build.md) is the better fit when the build is already expressed as +[`build.yml`](../build-workflow.md) is the better fit when the build is already expressed as a Dockerfile-oriented workflow. It lines up naturally with concepts such as `context`, `file`, `target`, `build-args`, `labels`, `annotations`, and `platforms`. This is the entrypoint that feels closest to `docker/build-push-action`, except the workflow implementation is centralized. -[`bake.yml`](bake.md) is the better fit when the repository already uses Bake +[`bake.yml`](../bake-workflow.md) is the better fit when the repository already uses Bake as the build definition. It preserves the Bake model, including target resolution, `files`, `set`, and `vars`, while still routing execution through the same Docker-maintained build path. One important architectural detail is @@ -124,7 +120,7 @@ selection and per-platform assembly. ### Dockerfile-oriented image build The following example shows the shape of a multi-platform image build driven -by [`build.yml`](build.md). +by [`build.yml`](../build-workflow.md). ```yaml name: ci diff --git a/content/manuals/build/ci/github-actions/github-builder/_index.md b/content/manuals/build/ci/github-actions/github-builder/_index.md deleted file mode 100644 index 4322d7968805..000000000000 --- a/content/manuals/build/ci/github-actions/github-builder/_index.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Docker GitHub Builder -linkTitle: GitHub Builder -description: Use Docker-maintained reusable GitHub Actions workflows to build images and artifacts with BuildKit. -keywords: ci, github actions, gha, buildkit, buildx, bake, reusable workflows -params: - sidebar: - badge: - color: green - text: New ---- - -Docker GitHub Builder is a set of [reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows) -in the [`docker/github-builder` repository](https://github.com/docker/github-builder) -for building container images and local artifacts with [BuildKit](../../../buildkit/_index.md). -This section explains what the workflows solve, how they differ from wiring -together individual GitHub Actions in each repository, and when to use -[`build.yml`](build.md) or [`bake.yml`](bake.md). - -If you compose a build job from `docker/login-action`, `docker/setup-buildx-action`, -`docker/metadata-action`, and either `docker/build-push-action` or -`docker/bake-action`, your repository owns every detail of how the build runs. -That approach works, but it also means every repository has to maintain its own -runner selection, [cache setup](../cache.md), [Provenance settings](../attestations.md), -signing behavior, and [multi-platform manifest handling](../multi-platform.md). -Docker GitHub Builder moves that implementation into Docker-maintained reusable -workflows, so your workflow only decides when to build and which inputs to pass. - -The difference is easiest to see in the job definition. A conventional workflow -spells out each action step: - -```yaml -jobs: - docker: - runs-on: ubuntu-latest - steps: - - name: Login to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up QEMU - uses: docker/setup-qemu-action@{{% param "setup_qemu_action_version" %}} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Docker meta - uses: docker/metadata-action@{{% param "metadata_action_version" %}} - id: meta - with: - images: name/app - - - name: Build and push - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: ${{ github.event_name != 'pull_request' }} - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - cache-from: type=gha - cache-to: type=gha -``` - -With Docker GitHub Builder, the same build is a reusable workflow call: - -```yaml -jobs: - build: - uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}} - 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 model gives you a build pipeline that is maintained in the Docker -organization, uses a pinned [BuildKit](../../../buildkit/_index.md) environment, -distributes [multi-platform builds](../../../building/multi-platform.md) across -runners when that helps, and emits signed [SLSA provenance](../../../metadata/attestations/slsa-provenance.md) -that records both the source commit and the builder identity. - -That tradeoff is intentional. You keep control of when the build runs and which -inputs it uses, but the build implementation itself lives in the -Docker-maintained workflow rather than in per-repository job steps. - -Use [`build.yml`](build.md) when your repository builds from a Dockerfile and -the familiar `build-push-action` inputs map cleanly to your workflow. Use -[`bake.yml`](bake.md) when your repository already describes builds in a -[Bake definition](../../../bake/_index.md), or when you want Bake targets, -overrides, and variables to stay as the source of truth. - -Both workflows support image output, local output, cache export to the -[GitHub Actions cache backend](../../../cache/backends/gha.md), -[SBOM generation](../../../metadata/attestations/sbom.md), and signing. The -Bake workflow adds Bake definition validation and builds one target per workflow -call. - -{{% sectionlinks %}} diff --git a/content/manuals/build/ci/github-actions/manage-tags-labels.md b/content/manuals/build/ci/github-actions/manage-tags-labels.md index 5e3f0e19158f..3d327af90c69 100644 --- a/content/manuals/build/ci/github-actions/manage-tags-labels.md +++ b/content/manuals/build/ci/github-actions/manage-tags-labels.md @@ -5,6 +5,64 @@ description: Assign tags and labels to images automatically with GitHub Actions keywords: ci, github actions, gha, buildkit, buildx, tags, labels --- +Use [Docker GitHub Builder](build-workflow.md) to generate tags and OCI +labels from GitHub events. Set `meta-images` and `meta-tags` to configure the +metadata action, and `set-meta-labels: true` to apply the generated labels. +This workflow publishes to Docker Hub and GitHub Container Registry on push +and scheduled events, and builds without publishing on pull requests: + +```yaml +name: ci + +on: + schedule: + - cron: "0 10 * * *" + push: + branches: + - "**" + tags: + - "v*.*.*" + pull_request: + +jobs: + build: + uses: docker/github-builder/.github/workflows/build.yml@{{% param "github_builder_version" %}} + permissions: + contents: read + id-token: write + packages: write + with: + output: image + push: ${{ github.event_name != 'pull_request' }} + set-meta-labels: true + meta-tags: | + type=schedule + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=semver,pattern={{major}} + type=sha + meta-images: | + name/app + ghcr.io/username/app + secrets: + registry-auths: | + - registry: docker.io + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} +``` + +Replace the image names with repositories you can push to. The +`packages: write` permission authorizes publishing to GitHub Container Registry. +GitHub Builder skips registry login and signing when `push` is false, so fork pull +requests don't need registry secrets. + +## Generate metadata with individual actions + If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md) for labels, you can do it in a dedicated setup step. The following workflow will use the [Docker Metadata Action](https://github.com/docker/metadata-action) diff --git a/content/manuals/build/ci/github-actions/multi-platform.md b/content/manuals/build/ci/github-actions/multi-platform.md index 1b03149a1257..9cb4894e3da3 100644 --- a/content/manuals/build/ci/github-actions/multi-platform.md +++ b/content/manuals/build/ci/github-actions/multi-platform.md @@ -1,10 +1,77 @@ --- title: Multi-platform image with GitHub Actions linkTitle: Multi-platform image -description: Build for multiple architectures with GitHub Actions using QEMU emulation or multiple native builders +description: Build multi-platform images with Docker GitHub Builder or individual actions using QEMU. keywords: ci, github actions, gha, buildkit, buildx, multi-platform --- +Use [Docker GitHub Builder](_index.md) to build multi-platform +images across native runners and publish a combined image manifest. + +## Distribute build across multiple runners + +Building multiple platforms on the same runner can significantly extend build +times, particularly when dealing with complex Dockerfiles or a high number of +target platforms. If you want to split platform builds across multiple runners +without maintaining a custom matrix and merge job, use the +[Docker GitHub Builder](_index.md). The reusable workflows +compute the per-platform matrix, run each platform on its own runner, and +create the final manifest for you. + +The following workflow uses the [`build.yml` reusable workflow](build-workflow.md) +to distribute a multi-platform Dockerfile build: + +```yaml +name: ci + +on: + push: + +permissions: + contents: read + +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 + platforms: linux/amd64,linux/arm64 + meta-images: user/app + meta-tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + secrets: + registry-auths: | + - registry: docker.io + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} +``` + +With `distribute: true`, which is the default, the workflow splits the build +into one platform per runner and assembles the final multi-platform image in +its finalize phase. The default `runner` mapping selects native GitHub-hosted +Linux runners for Arm and other platforms. To customize the mapping, see [runner selection](github-builder-architecture/index.md#runner-selection). +If you need to control the Docker build inputs directly, see +[Build with Docker GitHub Builder build.yml](build-workflow.md). + +### With Bake + +For builds defined in a Bake file, use the +[Bake reusable workflow](bake-workflow.md#build-and-push-a-bake-target). +It distributes the target's platforms and publishes the combined manifest. + +## Build with individual actions and QEMU + +Use individual actions when you need to configure the job's Docker Engine or +run other steps alongside the build. The following example uses QEMU to build +both platforms on one runner. + You can build [multi-platform images](../../building/multi-platform.md) using the `platforms` option, as shown in the following example: @@ -94,128 +161,3 @@ jobs: load: true tags: user/app:latest ``` - -## Distribute build across multiple runners - -Building multiple platforms on the same runner can significantly extend build -times, particularly when dealing with complex Dockerfiles or a high number of -target platforms. If you want to split platform builds across multiple runners -without maintaining a custom matrix and merge job, use the -[Docker GitHub Builder](github-builder/_index.md). The reusable workflows -compute the per-platform matrix, run each platform on its own runner, and -create the final manifest for you. - -The following workflow uses the [`build.yml` reusable workflow](github-builder/build.md) -to distribute a multi-platform Dockerfile build: - -```yaml -name: ci - -on: - push: - -permissions: - contents: read - -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 - platforms: linux/amd64,linux/arm64 - meta-images: user/app - meta-tags: | - type=ref,event=branch - type=ref,event=pr - type=semver,pattern={{version}} - type=semver,pattern={{major}}.{{minor}} - secrets: - registry-auths: | - - registry: docker.io - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} -``` - -With `distribute: true`, which is the default, the workflow splits the build -into one platform per runner and assembles the final multi-platform image in -its finalize phase. The default `runner` mapping sends Linux Arm platforms to -`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To customize -the mapping, see [runner selection](github-builder/architecture.md#runner-selection). -If you need to control the Docker build inputs directly, see -[Build with Docker GitHub Builder build.yml](github-builder/build.md). - -### With Bake - -You can use the [`bake.yml` reusable workflow](github-builder/bake.md) for the -same pattern when your build is defined in a Bake file. The workflow reads the -target platforms from the Bake definition, distributes the per-platform builds, -and publishes the final manifest without a separate prepare or merge job. - -```hcl -variable "DEFAULT_TAG" { - default = "app:local" -} - -// Special target: https://github.com/docker/metadata-action#bake-definition -target "docker-metadata-action" { - tags = ["${DEFAULT_TAG}"] -} - -// Default target if none specified -group "default" { - targets = ["image-local"] -} - -target "image" { - inherits = ["docker-metadata-action"] -} - -target "image-local" { - inherits = ["image"] - output = ["type=docker"] -} - -target "image-all" { - inherits = ["image"] - platforms = [ - "linux/amd64", - "linux/arm/v6", - "linux/arm/v7", - "linux/arm64" - ] -} -``` - -```yaml -name: ci - -on: - push: - -permissions: - contents: read - -jobs: - bake: - uses: docker/github-builder/.github/workflows/bake.yml@{{% param "github_builder_version" %}} - permissions: - contents: read - id-token: write - with: - output: image - push: true - target: image-all - meta-images: user/app - meta-tags: | - type=ref,event=branch - type=sha - secrets: - registry-auths: | - - registry: docker.io - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} -``` diff --git a/content/manuals/build/ci/github-actions/push-multi-registries.md b/content/manuals/build/ci/github-actions/push-multi-registries.md index e80bbc456b45..8b2a6a237f41 100644 --- a/content/manuals/build/ci/github-actions/push-multi-registries.md +++ b/content/manuals/build/ci/github-actions/push-multi-registries.md @@ -5,6 +5,49 @@ description: Push to multiple registries with GitHub Actions keywords: ci, github actions, gha, buildkit, buildx, registry --- +Use [Docker GitHub Builder](build-workflow.md) to publish to multiple +registries. List the image names in `meta-images` and credentials in the +`registry-auths` secret. This example publishes `latest` and `1.0.0` tags to +Docker Hub and GitHub Container Registry: + +```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 + packages: write + with: + output: image + push: true + platforms: linux/amd64,linux/arm64 + meta-tags: | + type=raw,value=latest + type=raw,value=1.0.0 + meta-images: | + user/app + ghcr.io/user/app + secrets: + registry-auths: | + - registry: docker.io + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} +``` + +Replace the image names with repositories you can push to. The +`packages: write` permission authorizes publishing to GitHub Container Registry. + +## Push with individual actions + The following workflow will connect you to Docker Hub and GitHub Container Registry, and push the image to both registries: @@ -16,6 +59,9 @@ on: jobs: docker: + permissions: + contents: read + packages: write runs-on: ubuntu-latest steps: - name: Login to Docker Hub diff --git a/content/manuals/build/ci/github-actions/reproducible-builds.md b/content/manuals/build/ci/github-actions/reproducible-builds.md index 0649ca534934..9beaa2692eb0 100644 --- a/content/manuals/build/ci/github-actions/reproducible-builds.md +++ b/content/manuals/build/ci/github-actions/reproducible-builds.md @@ -12,13 +12,41 @@ image index, config, and file metadata reflect the specified Unix time. [source_date_epoch]: https://reproducible-builds.org/docs/source-date-epoch/ -To set the environment variable in GitHub Actions, -use the built-in `env` property on the build step. +With Docker GitHub Builder, pass `SOURCE_DATE_EPOCH` as a build argument. +With individual actions, use the built-in `env` property on the build step. ## Unix epoch timestamps The following example sets the `SOURCE_DATE_EPOCH` variable to 0, Unix epoch. +### Set the epoch with GitHub Builder {#set-the-epoch-with-builder} + +Pass the fixed epoch through the [Build workflow](build-workflow.md): + +```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 + build-args: | + SOURCE_DATE_EPOCH=0 + meta-images: user/app +``` + +For the [Bake workflow](bake-workflow.md), set +`*.args.SOURCE_DATE_EPOCH=0` using the `set` input. + +### Set the epoch with individual actions + {{< tabs group="action" >}} {{< tab name="`docker/build-push-action`" >}} @@ -70,7 +98,10 @@ jobs: ## Git commit timestamps -The following example sets `SOURCE_DATE_EPOCH` to the Git commit timestamp. +The following individual-action examples set `SOURCE_DATE_EPOCH` to the Git +commit timestamp. Keep timestamp generation in the caller when it depends on +a workflow step. A reusable workflow call cannot reference earlier steps in +the same job. {{< tabs group="action" >}} {{< tab name="`docker/build-push-action`" >}} diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md index edc7b045c47d..51330f11e1d7 100644 --- a/content/manuals/build/ci/github-actions/secrets.md +++ b/content/manuals/build/ci/github-actions/secrets.md @@ -29,6 +29,41 @@ FROM alpine RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ... ``` +### Pass secret values with GitHub Builder {#pass-secret-values-with-builder} + +Pass secret values to [Docker GitHub Builder](build-workflow.md) using +the `build-secrets` workflow secret. Its value is a YAML mapping from secret +IDs to values, rather than the action's `id=value` list: + +```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 + platforms: linux/amd64,linux/arm64 + meta-images: user/app + secrets: + build-secrets: | + github_token: ${{ toJSON(secrets.GITHUB_TOKEN) }} +``` + +The Dockerfile consumes the `github_token` secret in the same way with either +workflow. `toJSON` quotes the value for the YAML mapping. +For files, environment variables, or SSH agents prepared by earlier steps, +use the individual-action examples below. The reusable build runs in separate +jobs and doesn't share the caller's filesystem or SSH agent. + +### Pass secret values with individual actions + In this example, the secret name is `github_token`. The following workflow exposes this secret using the `secrets` input: @@ -257,8 +292,7 @@ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \ ### Multi-line secrets If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) -and need to handle multi-line value, you will need to place the key-value pair -between quotes: +with individual actions, place multi-line key-value pairs between quotes: ```yaml secrets: | diff --git a/layouts/_shortcodes/sectionlinks.html b/layouts/_shortcodes/sectionlinks.html deleted file mode 100644 index 51b9f633e4dd..000000000000 --- a/layouts/_shortcodes/sectionlinks.html +++ /dev/null @@ -1,3 +0,0 @@ -{{ range .Page.Pages }} -- [{{ .Title }}]({{ .RelPermalink }}) -{{ end }}