diff --git a/content/build/ci/github-actions/build-summary.md b/content/build/ci/github-actions/build-summary.md new file mode 100644 index 000000000000..b31408b1a9a2 --- /dev/null +++ b/content/build/ci/github-actions/build-summary.md @@ -0,0 +1,86 @@ +--- +title: GitHub Actions build summary +descripion: Get an overview of your Docker Builds with GitHub Actions +keywords: github actions, gha, build, summary, annotation +--- + +Docker's GitHub Actions for building and pushing images generate a job summary +for your build that outlines the execution and materials used: + +- A summary showing the Dockerfile used, the build duration, and cache utilization +- Inputs for the build, such as build arguments, tags, labels, and build contexts +- For builds with [Bake](../../bake/_index.md), the full bake definition for the build + +![A GitHub Actions build summary](../images/gha_build_summary.png) + +Job summaries for Docker builds appear automatically if you use the following +versions of the [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images) +or [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake) +GitHub Actions: + +- `docker/build-push-action@v5.4.0` or `docker/build-push-action@v5` +- `docker/bake-action@v4.6.0` or `docker/bake-action@v4` + +> **Note** +> +> Job summaries are not yet supported with [Docker Build Cloud](../../cloud/_index.md). + +To view the job summary, open the details page for the job in GitHub after the +job has finished. The summary is available for both failed and successful +builds. In the case of a failed build, the summary also displays the error +message that caused the build to fail: + +![Builds summary error message](../images/build_summary_error.png) + +## Import build records to Docker Desktop + +{{< introduced desktop 4.31 >}} + +> **Beta feature** +> +> Import builds is currently in [Beta](../../../release-lifecycle.md#Beta). +{ .experimental } + +The job summary includes a link for downloading a build record archive for the +run. The build record archive is a ZIP file containing the details about a build +(or builds, if you use `docker/bake-action` to build multiple targets). You can +import this build record archive into Docker Desktop, which gives you a +powerful, graphical interface for further analyzing the build's performance via +the [Docker Desktop **Builds** view](../../../desktop/use-desktop/builds.md). + +To import the build record archive into Docker Desktop: + +1. Download and install [Docker Desktop](../../../get-docker.md). + +2. Download the build record archive from the job summary in GitHub Actions. + +3. Open the **Builds** view in Docker Desktop. + +4. Select the **Import build** button, and then browse for the `.zip` archive + job summary that you downloaded. Alternatively, you can drag-and-drop the + build record archive ZIP file onto the Docker Desktop window after opening + the import build dialog. + +5. Select **Import** to add the build records. + +After a few seconds, the builds from the GitHub Actions run appear under the +**Completed builds** tab in the Builds view. To inspect a build and see a +detailed view of all the inputs, results, build steps, and cache utilization, +select the item in the list. + +## Disable job summary + +To disable job summaries, set the `DOCKER_BUILD_NO_SUMMARY` environment +variable in the YAML configuration for your build step: + +```yaml {hl_lines=5} + - + name: Build + uses: docker/docker-build-push-action@v5 + env: + DOCKER_BUILD_NO_SUMMARY: true + with: + context: . + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} +``` diff --git a/content/build/ci/images/build_summary_error.png b/content/build/ci/images/build_summary_error.png new file mode 100644 index 000000000000..420bed060ad0 Binary files /dev/null and b/content/build/ci/images/build_summary_error.png differ diff --git a/content/build/ci/images/gha_build_summary.png b/content/build/ci/images/gha_build_summary.png new file mode 100644 index 000000000000..140e76e62902 Binary files /dev/null and b/content/build/ci/images/gha_build_summary.png differ diff --git a/content/desktop/use-desktop/builds.md b/content/desktop/use-desktop/builds.md index 326fc6c4ba12..869ac7705003 100644 --- a/content/desktop/use-desktop/builds.md +++ b/content/desktop/use-desktop/builds.md @@ -23,21 +23,35 @@ connected to the same cloud builder. Select the **Builds** view in the Docker Dashboard to open the build list. -The build list shows running and completed builds for your active builders. The -top-right corner shows the name of your currently selected builder, and the +The build list shows your completed and ongoing builds. The **Build history** +tab shows completed historical builds, and from here you can inspect the build +logs, dependencies, traces, and more. The **Active builds** tab shows builds +that are currently running. + +The list shows builds for your active, running builders. It doesn't list builds +for inactive builders: builders that you've removed from your system, or +builders that have been stopped. + +### Builder settings + +The top-right corner shows the name of your currently selected builder, and the **Builder settings** button lets you [manage builders](#manage-builders) in the Docker Desktop settings. -Running builds are displayed in the top section of this view, with information -about the build target and progress. +### Import builds -The lower section of the view shows your recent builds. You can select any of -the builds from the active builds or completed builds section to view detailed -information, such as logs, a performance breakdown, cache utilization, and -more. +> **Beta feature** +> +> Import builds is currently in [Beta](../../release-lifecycle.md#Beta). +{ .experimental } -The build list doesn't include builds for inactive builders. That is, builders -that you've removed from your system, or builders that have been stopped. +The **Import builds** button lets you import build records for builds by other +people, or builds in a CI environment. When you've imported a build record, it +gives you full access to the logs, traces, and other data for that build, +directly in Docker Desktop. The [build summary](../../build/ci/github-actions/build-summary.md) +for the `docker/build-push-action` and `docker/bake-action` GitHub Actions +includes a link to download the build records, for inspecting CI jobs with +Docker Desktop. ## Inspect builds diff --git a/data/redirects.yml b/data/redirects.yml index 7506d922904a..8f584e9b56af 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -682,6 +682,10 @@ - /go/build-additional-context/ "/config/labels-custom-metadata/": - /go/labels/ +"/build/ci/github-actions/build-summary/": + - /go/build-summary/ +"/desktop/use-desktop/builds/#import-builds": + - /go/builds-import/ # Build links (external) "https://www.docker.com/build-early-access-program/?utm_campaign=onboard-30-customer-zero&utm_medium=in-product-ad&utm_source=desktop_v4": diff --git a/data/toc.yaml b/data/toc.yaml index b675f3e7c7b5..3424dd3915d5 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1949,6 +1949,8 @@ Manuals: section: - path: /build/ci/github-actions/ title: Introduction + - path: /build/ci/github-actions/build-summary/ + title: Build summary - path: /build/ci/github-actions/configure-builder/ title: Configuring your builder - path: /build/ci/github-actions/multi-platform/