Generate and validate build provenance

This page provides instructions on how to generate build provenance, view the output, and validate it.

Build provenance is a collection of verifiable data about a build. Provenance metadata includes details such as the digests of the built images, the input source locations, the build arguments, and the build duration. You can use this information to ensure that the built artifacts you are using are accurate and reliable, created by trusted sources and builders.

Cloud Build supports the generation of build provenance that meets Supply-chain Levels for Software Artifacts (SLSA) level 3 assurance based on the specifications for SLSA version 0.1 and 1.0.

As part of support for the SLSA v1.0 spec, Cloud Build provides buildType details in build provenance. You can use the buildType schema to understand the parameterized template used for the build process, including the values that Cloud Build records, and the source of those values. For more information, see Cloud Build buildType v1.

Limitations

• Cloud Build only generates build provenance for artifacts stored in Artifact Registry.
• Repository attachments, including build provenance, aren't subject to cleanup policies. Instead, attachments are deleted when the image they are attached to is deleted. For more information, see Manage attachments with cleanup policies.

Before you begin

1. Enable the Cloud Build, Container Analysis, and Artifact Registry APIs.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the APIs

2. To use the command-line examples in this guide, install and configure the Google Cloud SDK.

3. Have your source code handy.

4. Have a repository in Artifact Registry.

Generate build provenance

The following instructions explain how to generate build provenance for container images you store in Artifact Registry:

1. In your build config file, add the images field to configure Cloud Build to store your built images in Artifact Registry after your build completes.

   Cloud Build can't generate provenance if you push your image to Artifact Registry using an explicit docker push step.

   The following snippet shows a build config to build a container image and store the image in a Docker repository in Artifact Registry:

   YAML

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE', '.' ]