Add SBOM and provenance attestations with GitHub Actions

Table of contents

Software Bill of Material (SBOM) and provenance attestationsadd 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

Thedocker/build-push-actionGitHub Action automatically adds provenance attestations to your image, with the following conditions:

  • If the GitHub repository is public, provenance attestations withmode=max are automatically added to the image.
  • If the GitHub repository is private, provenance attestations withmode=min are automatically added to the image.
  • If you're using the dockerexporter,or you're loading the build results to the runner withload: true,no attestations are added to the image. These output formats don't support attestations.

Warning

If you're usingdocker/build-push-actionto build images for code in a public GitHub repository, the provenance attestations attached to your image by default contains the values of build arguments. If you're misusing build arguments to pass secrets to your build, such as user credentials or authentication tokens, those secrets are exposed in the provenance attestation. Refactor your build to pass those secrets using secret mounts instead. Also remember to rotate any secrets you may have exposed.

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 theprovenance input on thedocker/build-push-actionGitHub Action tomode=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.

name:ci

on:
push:

env:
IMAGE_NAME:user/app

jobs:
docker:
runs-on:ubuntu-latest
steps:
-name:Set up Docker Buildx
uses:docker/setup-buildx-action@v3

-name:Login to Docker Hub
uses:docker/login-action@v3
with:
username:${{ vars.DOCKERHUB_USERNAME }}
password:${{ secrets.DOCKERHUB_TOKEN }}

-name:Extract metadata
id:meta
uses:docker/metadata-action@v5
with:
images:${{ env.IMAGE_NAME }}

-name:Build and push image
uses:docker/build-push-action@v6
with:
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 thesbominput of thedocker/build-push-actionto 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.

name:ci

on:
push:

env:
IMAGE_NAME:user/app

jobs:
docker:
runs-on:ubuntu-latest
steps:
-name:Set up Docker Buildx
uses:docker/setup-buildx-action@v3

-name:Login to Docker Hub
uses:docker/login-action@v3
with:
username:${{ vars.DOCKERHUB_USERNAME }}
password:${{ secrets.DOCKERHUB_TOKEN }}

-name:Extract metadata
id:meta
uses:docker/metadata-action@v5
with:
images:${{ env.IMAGE_NAME }}

-name:Build and push image
uses:docker/build-push-action@v6
with:
sbom:true
push:true
tags:${{ steps.meta.outputs.tags }}