v1

Build Type: GCB Triggered Build

This build type is now deprecated. For the current SLSA Provenance for Cloud Build, see https://docs.cloud.google.com/build/gcb-buildtypes/google-worker/v1.

This is a community-maintained SLSA Provenance buildType that describes the execution a build by Google Cloud Build reading the build configuration from source.

This definition is hosted and maintained by the SLSA community, not Google. Our hope is for Google Cloud Build to eventually host and maintain this definition, served under a URL it controls, once it officially supports SLSA. In the meantime, this unofficial definition can be used by tooling that runs on top of GCB to describe a Google Cloud Build.

Description

"buildType": "https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1"

This buildType describes the execution of a Google Cloud Build (GCB) build where GCB read the build configuration from a file in a source repository, usually called cloudbuild.yaml. This is only possible via a Trigger, though theoretically a future API or CLI call could do the same.

This buildType MUST NOT be used to describe:

• Cases where GCB did not verify that the build configuration came from a source repository. This includes local builds that send the Build over the wire, as well as Triggers that set an explicit build. (If desired, a separate buildType could be created for that purpose.)
• Pull request events. The semantics are confusing in the context of SLSA since the build is not of the target but of the source, so to be safe these are unsupported.

If you have a use case for supporting these, please open a GitHub Issue.

Build Definition

External parameters

All external parameters are REQUIRED unless otherwise noted.

Parameter	Type	Description
configSource	object	Location from which the build configuration was read. In BuildTrigger, this corresponds to either gitFileSource or the source repo that triggered the build, depending on the trigger type.
configSource.ref	object	Git reference within configSource.repository from which the configuration was read, as either a fully qualified git ref (starting with refs/) or a commit SHA (lowercase hex). A commit SHA is only used if specified in the trigger.
configSource.repository	string	HTTPS URI of the git repository containing the build configuration file, with https:// protocol and without .git suffix.
configSource.path	string	Path to the build configuration file within the commit. Example: cloudbuild.yaml Mutually exclusive with pathAutodetect. Exactly one of these fields MUST be set.
configSource.pathAutodetect	boolean	If true, path was autodetected, corresponding to the autodetect option in the BuildTrigger. This MUST NOT be set to false; use path instead if autodetection was not enabled. Mutually exclusive with path. Exactly one of these fields MUST be set.
sourceToBuild	object	Source code that was checked out and built. Normally this is the same as configSource; it only differs if the BuildTrigger had gitFileSource set. This field SHOULD be omitted if the repository and ref are the same as configSource and the dir is empty. In BuildTrigger, this corresponds to either sourceToBuild or the commit that triggered the build, depending on the trigger type.
sourceToBuild.ref	string	Git reference within sourceToBuild.repository that was checked out, as either a fully qualified git ref (starting with refs/) or a commit SHA (lowercase hex). A commit SHA is only used if specified in the trigger.
sourceToBuild.repository	string	HTTPS URI of the git repository that was checked out, with https:// protocol and without .git suffix.
sourceToBuild.dir	string	Directory within the commit in which to run the build, without a trailing slash. Can be empty / unset.
substitutions	object	Map of (string -> string) containing the substitutions to perform on the Build resource. In BuildTrigger, this corresponds to substitutions.

Internal parameters

All internal parameters are OPTIONAL.

Parameter	Type	Description
configSource	RepositoryInfo	Metadata about externalParameters.configSource.
projectId	string	Immutable project ID containing this build. Does not impact the provenance but affects what resources the build can access.
serviceAccount	string	Service account that the build ran under. Does not impact the provenance but affects what resources the build can access.
sourceToBuild	RepositoryInfo	Metadata about externalParameters.sourceToBuild.
triggerUri	string	Resource URI of the trigger that invoked this build.

RepositoryInfo describes metadata about a repository.

RepositoryInfo	Type	Description
repoType	string (RepoType)	The hosting provider of repository in case it cannot be determined from the URI, such as for an enterprise account with a custom domain.
repositoryId	string	The immutable (numeric) ID of repository provided by the source control host, if known.
repositoryOwnerId	string	The immutable (numeric) ID of the user or organization that owns repository, if known.

Immutable IDs can be used to provide stable identifiers across account and repository renames and to detect when an old name is reused for a new entity.

Resolved dependencies

The resolvedDependencies SHOULD contain entries identifying the resolved git commit IDs corresponding to externalParameters.configSource and externalParameters.sourceToBuild. The dependencies' uri MUST be in SPDX Download Location format, i.e. "git+" + repository + "@" + ref. See Examples.

The resolvedDependencies MAY contain additional artifacts known to be input to the workflow.

Run details

Metadata

The invocationId SHOULD be set to the URL of the build resource, i.e. https://cloudbuild.googleapis.com/v1/projects/<project>/locations/<location>/builds/<build_id>.

Examples

See example.json.

Version history

v1

Initial version