diff --git a/content/build/ci/github-actions/_index.md b/content/build/ci/github-actions/_index.md index 6e8ae83cff..8bbd465ae4 100644 --- a/content/build/ci/github-actions/_index.md +++ b/content/build/ci/github-actions/_index.md @@ -51,7 +51,7 @@ refer to the following sections: - [Share built image between jobs](share-image-jobs.md) - [Test before push](test-before-push.md) - [Update Docker Hub repository description](update-dockerhub-desc.md) -- [Analyzing images with Docker Scout](../../../scout/integrations/ci/gha.md) +- [SBOM and provenance attestations](attestations.md) ## Get started with GitHub Actions diff --git a/content/build/ci/github-actions/attestations.md b/content/build/ci/github-actions/attestations.md new file mode 100644 index 0000000000..70096ece0b --- /dev/null +++ b/content/build/ci/github-actions/attestations.md @@ -0,0 +1,183 @@ +--- +title: Add SBOM and provenance attestations with GitHub Actions +description: Add SBOM and provenance attestations to your images with GitHub Actions +keywords: ci, github actions, gha, buildkit, buildx, attestations, sbom, provenance, slsa +--- + +Software Bill of Material (SBOM) and provenance +[attestations](../../attestations/_index.md) add metadata about the contents of +your image, and how it was built. + +Attestations are supported with version 4 and later of the +`docker/build-push-action`. + +## Default provenance + +The `docker/build-push-action` GitHub Action automatically adds provenance +attestations to your image, with the following conditions: + +- If the GitHub repository is public, provenance attestations with `mode=max` + are automatically added to the image. +- If the GitHub repository is private, provenance attestations with `mode=min` + are automatically added to the image. +- If you're using the [`docker` exporter](../../exporters/oci-docker.md), or + you're loading the build results to the runner with `load: true`, no + attestations are added to the image. These output formats don't support + attestations. + +## Max-level provenance + +It's recommended that you build your images with max-level provenance +attestations. Private repositories only add min-level provenance by default, +but you can manually override the provenance level by setting the `provenance` +input on the `docker/build-push-action` GitHub Action to `mode=max`. + +Note that adding attestations to an image means you must push the image to a +registry directly, as opposed to loading the image to the local image store of +the runner. This is because the local image store doesn't support loading +images with attestations. + +```yaml +name: ci + +on: + push: + branches: + - "main" + +env: + IMAGE_NAME: user/app + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v4 + with: + images: ${{ env.IMAGE_NAME }} + + - name: Build and push image + uses: docker/build-push-action@v5 + with: + context: . + push: true + provenance: mode=max + tags: ${{ steps.meta.outputs.tags }} +``` + +## SBOM + +SBOM attestations aren't automatically added to the image. To add SBOM +attestations, set the `sbom` input of the `docker/build-push-action` to `true. + +Note that adding attestations to an image means you must push the image to a +registry directly, as opposed to loading the image to the local image store of +the runner. This is because the local image store doesn't support loading +images with attestations. + +```yaml +name: ci + +on: + push: + branches: + - "main" + +env: + IMAGE_NAME: user/app + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v4 + with: + images: ${{ env.IMAGE_NAME }} + + - name: Build and push image + uses: docker/build-push-action@v5 + with: + context: . + sbom: true + tags: ${{ steps.meta.outputs.tags }} +``` + +## SBOM + +SBOM attestations aren't automatically added to the image. To add SBOM +attestations, set the `sbom` input of the `docker/build-push-action` to `true. + +Note that adding attestations to an image means you must push the image to a +registry directly, as opposed to loading the image to the local image store of +the runner. This is because the local image store doesn't support loading +images with attestations. + +```yaml +name: ci + +on: + push: + branches: + - "main" + +env: + IMAGE_NAME: user/app + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v4 + with: + images: ${{ env.IMAGE_NAME }} + + - name: Build and push image + uses: docker/build-push-action@v5 + with: + context: . + sbom: true + push: true + tags: ${{ steps.meta.outputs.tags }} +``` diff --git a/data/redirects.yml b/data/redirects.yml index 0692444cb6..a0792ce8dd 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -621,6 +621,8 @@ - /go/build-exporters/ "/build/bake/reference/": - /build/customize/bake/file-definition/ +"/build/ci/github-actions/attestations/": + - /go/build-attestations-gha/ # CLI backlinks "/config/filter/": diff --git a/data/toc.yaml b/data/toc.yaml index 11d6af462f..8b196e0b85 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1907,6 +1907,8 @@ Manuals: title: Copy image between registries - path: /build/ci/github-actions/update-dockerhub-desc/ title: Update Docker Hub repo description + - path: /build/ci/github-actions/attestations/ + title: SBOM and provenance attestations - path: /build/release-notes/ title: Release notes - sectiontitle: Docker Compose