gha attestations ex

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
 

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 }}
+```

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/":

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