Software Bill of Material (SBOM) and provenance attestations 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, 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 using
docker/build-push-action
to 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 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.
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 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.
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 }}