This page explains the [**Build Type**](https://slsa.dev/provenance/v1#schema)
for Cloud Build.

## Build definition

### External parameters

The following table displays the types of external parameters that may be used
in a Cloud Build build. External parameters are values that you
specify, and aren't present in your build configuration. This includes trigger
parameters that aren't in your your `cloudbuild.yaml` file.

| Field | Type | Details |
|---|---|---|
| buildConfigSource | object | Location from which the build configuration was read. <br /> In `BuildTrigger`, this corresponds to either the source repo that triggered the build (SCM event-triggered builds) or `gitFileSource` for all other trigger types. <br /> Either `buildConfigSource` OR `buildConfig` (in the case of inline build config) will be set. |
| buildConfigSource.ref | string | Git reference within `buildConfigSource.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. |
| buildConfigSource.repository | string | HTTPS URI of the git repository containing the build configuration file, with `https://` protocol. This will be prefixed with a `git+` for compatibility with the [SPDX](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field) format. For more information on the format requirements, see [ResourceURI](https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#resourceuri). |
| buildConfigSource.path | string | Path to the build configuration file within the commit. Example: `cloudbuild.yaml` <br /> Mutually exclusive with pathAutodetect. Exactly one of these fields *must* be set to a non-default value. |
| buildConfigSource.pathAutoDetect | boolean | If true, `path` was autodetected, corresponding to the autodetect option in the `BuildTrigger`. False is considered equivalent to not set; Cloud Build uses `path` instead if autodetection was not enabled. <br /> Mutually exclusive with `path`. Exactly one of these fields MUST be set to a non-default value. |
| sourceToBuild | object | Source code that was checked out and built. Normally this is the same as `buildConfigSource`; it only differs if the BuildTrigger had `gitFileSource` set. <br /> This field does not exist if the `repository` and `ref` are the same as `buildConfigSource` and the `dir` is empty. <br /> 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. This will be prefixed with a `git+`. |
| sourceToBuild.dir | string | Directory within the commit in which to run the build, without a trailing slash. Can be empty, unset. |
| buildConfig | string | When an inline build config is provided, such as in a manually submitted build, the following information is recorded. <br /> - steps - build options (e.g. environment variables, volumes, worker pool details, machineType, log details) - substitutions <br /> If the build config was read from a repository, it is recorded in the `buildConfigSource` section and the inline build config is omitted. <br /> This information is stored as a base64 encoded serialized JSON string. |
| substitutions | map | Map of (string -\> string) containing the substitutions to perform on the Build resource. <br /> This only contains "runtime" or "independent" substitutions which are not recorded in the build config, i.e. passed in from a trigger or gcloud CLI flag. <br /> This record does not include the system-provided [default substitutions](https://docs.cloud.google.com/build/docs/configuring-builds/substitute-variable-values#using_default_substitutions) as those are considered `internalParameters`. <br /> Substitutions appear in this field regardless of whether they are referenced or used in the build config. |

### Internal parameters

The following table displays the internal parameters that Cloud Build
sets for the build, unless you overwrite them. For more information, see
[default substitutions](https://docs.cloud.google.com/build/docs/configuring-builds/substitute-variable-values#using_default_substitutions).

| Field | Details |
|---|---|
| triggerUri | Resource URI of the trigger that invoked this build, in this case the full resource name. <br /> If the build was not triggered, this is omitted. |
| systemSubstitutions | There is a subset of [default substitution values](https://docs.cloud.google.com/build/docs/configuring-builds/substitute-variable-values#using_default_substitutions) which are automatically provided in Cloud Build builds, such as `PROJECT_ID`, `BUILD_ID`. <br /> If you overwrite one of the Cloud Build default substitutions, your substitutions won't be displayed here. Your values will be listed in `externalParameters.substitutions` instead. |

### Resolved dependencies

If the build has a source repository or a build config repository, the
repository is described in the
[`resolvedDependencies`](https://slsa.dev/provenance/v1#resolvedDependencies)
section of the `BuildDefinition`.

`ResolvedDependencies` conform to the
[`ResourceDescriptor` specification](https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md).

| Dependency type | Details |
|---|---|
| Build config repository | The repo that the build config (i.e. the `cloudbuild.yaml`) was pulled from, in the case of triggered builds. <br /> <br /> This may be empty in the case of a build config which was not read from a repo and is provided inline, in which case it will be omitted. |
| Source repository | The repo that the source code to build was pulled from. It could be the same as `buildConfigSource`, or different. If the same as `buildConfigSource`, the `sourceToBuild` is omitted, for example, in SCM-triggered builds. <br /> The `sourceToBuild` may be empty if the build is run via `--no-source`, and will be omitted. |

For example, the following `resolvedDependencies` info contains both a
buildConfigRepo and sourceRepo (which are the same), and a build step image.

    "resolvedDependencies": [
    {
        "uri": "git+https://github.com/octocat/hello-world.git",
        "digest": {"sha1": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"}
    }, {
        "uri": "gcr.io/cloud-builders/git",
        "digest": {
            "sha256": "28ff94e63e4058afc3f15b4c11c08cf3b54fa91faa646a4bba7158df"}
        }
    ]

## RunDetails

| Field | Details |
|---|---|
| builder | Contains an `id` subfield that identifies the build platform that executed the operation and populated this provenance. This also contains the SLSA level. The expected `id` value is `https://cloudbuild.googleapis.com/GoogleHostedWorker`. |
| metadata | Additional metadata about this particular execution of the build. The `invocationId` displays the URL of the build, such as `https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/builds/BUILD_ID`. The `startedOn` and `finishedOn` fields contain the timestamps for when the build started and completed. |
| byproducts | Not in use yet. Designed to contain additional artifacts that are not considered the output of the build, but might be useful for troubleshooting or incident response. |
| systemSubstitutions | There is a subset of [default substitution values](https://docs.cloud.google.com/build/docs/configuring-builds/substitute-variable-values#using_default_substitutions) which are automatically provided in Cloud Build builds, such as `PROJECT_ID`, `BUILD_ID`. <br /> If you overwrite one of the Cloud Build default substitutions, your substitutions won't be displayed here. Your values will be listed in `externalParameters.substitutions` instead. |