REST Resource: projects.locations.builds

Resource: Build

A build resource in the Cloud Build API.

At a high level, a Build describes where to find source code, how to build it (for example, the builder image to run on the source), and where to store the built artifacts.

Fields can include the following variables, which will be expanded when the build is created:

  • $PROJECT_ID: the project ID of the build.
  • $PROJECT_NUMBER: the project number of the build.
  • $LOCATION: the location/region of the build.
  • $BUILD_ID: the autogenerated ID of the build.
  • $REPO_NAME: the source repository name specified by RepoSource.
  • $BRANCH_NAME: the branch name specified by RepoSource.
  • $TAG_NAME: the tag name specified by RepoSource.
  • $REVISION_ID or $COMMIT_SHA: the commit SHA specified by RepoSource or resolved from the specified branch or tag.
  • $SHORT_SHA: first 7 characters of $REVISION_ID or $COMMIT_SHA.
JSON representation 
{
  "name": string,
  "id": string,
  "projectId": string,
  "status": enum (Status),
  "statusDetail": string,
  "source": {
    object (Source)
  },
  "steps": [
    {
      object (BuildStep)
    }
  ],
  "results": {
    object (Results)
  },
  "createTime": string,
  "startTime": string,
  "finishTime": string,
  "timeout": string,
  "images": [
    string
  ],
  "queueTtl": string,
  "artifacts": {
    object (Artifacts)
  },
  "logsBucket": string,
  "sourceProvenance": {
    object (SourceProvenance)
  },
  "buildTriggerId": string,
  "options": {
    object (BuildOptions)
  },
  "logUrl": string,
  "substitutions": {
    string: string,
    ...
  },
  "tags": [
    string
  ],
  "secrets": [
    {
      object (Secret)
    }
  ],
  "timing": {
    string: {
      object (TimeSpan)
    },
    ...
  },
  "approval": {
    object (BuildApproval)
  },
  "serviceAccount": string,
  "availableSecrets": {
    object (Secrets)
  },
  "warnings": [
    {
      object (Warning)
    }
  ],
  "gitConfig": {
    object (GitConfig)
  },
  "failureInfo": {
    object (FailureInfo)
  }
}
Fields
name

string

Output only. The 'Build' name with format: projects/{project}/locations/{location}/builds/{build}, where {build} is a unique identifier generated by the service.
id

string

Output only. Unique identifier of the build.
projectId

string

Output only. ID of the project.
status

enum (Status)

Output only. Status of the build.
statusDetail

string

Output only. Customer-readable message about the current status.
source

object (Source)

Optional. The location of the source files to build.
steps[]

object (BuildStep)

Required. The operations to be performed on the workspace.
results

object (Results)

Output only. Results of the build.
createTime

string (Timestamp format)

Output only. Time at which the request to create the build was received.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
startTime

string (Timestamp format)

Output only. Time at which execution of the build was started.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
finishTime

string (Timestamp format)

Output only. Time at which execution of the build was finished.

The difference between finishTime and startTime is the duration of the build's execution.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
timeout

string (Duration format)

Amount of time that this build should be allowed to run, to second granularity. If this amount of time elapses, work on the build will cease and the build status will be TIMEOUT.

timeout starts ticking from startTime.

Default time is 60 minutes.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
images[]

string

A list of images to be pushed upon the successful completion of all build steps.

The images are pushed using the builder service account's credentials.

The digests of the pushed images will be stored in the Build resource's results field.

If any of the images fail to be pushed, the build status is marked FAILURE.
queueTtl

string (Duration format)

TTL in queue for this build. If provided and the build is enqueued longer than this value, the build will expire and the build status will be EXPIRED.

The TTL starts ticking from createTime.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
artifacts

object (Artifacts)

Artifacts produced by the build that should be uploaded upon successful completion of all build steps.
logsBucket

string

Cloud Storage bucket where logs should be written (see Bucket Name Requirements). Logs file names will be of the format ${logsBucket}/log-${build_id}.txt.
sourceProvenance

object (SourceProvenance)

Output only. A permanent fixed identifier for source.
buildTriggerId

string

Output only. The ID of the BuildTrigger that triggered this build, if it was triggered automatically.
options

object (BuildOptions)

Special options for this build.
logUrl

string

Output only. URL to logs for this build in Google Cloud Console.
substitutions

map (key: string, value: string)

Substitutions data for Build resource.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
tags[]

string

Tags for annotation of a Build. These are not docker tags.
secrets[]

object (Secret)

Secrets to decrypt using Cloud Key Management Service. Note: Secret Manager is the recommended technique for managing sensitive data with Cloud Build. Use availableSecrets to configure builds to access secrets from Secret Manager. For instructions, see: https://cloud.google.com/cloud-build/docs/securing-builds/use-secrets
timing

map (key: string, value: object (TimeSpan))

Output only. Stores timing information for phases of the build. Valid keys are:

  • BUILD: time to execute all build steps.
  • PUSH: time to push all artifacts including docker images and non docker artifacts.
  • FETCHSOURCE: time to fetch source.
  • SETUPBUILD: time to set up build.

If the build does not specify source or images, these keys will not be included.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
approval

object (BuildApproval)

Output only. Describes this build's approval configuration, status, and result.
serviceAccount

string

IAM service account whose credentials will be used at build runtime. Must be of the format projects/{PROJECT_ID}/serviceAccounts/{ACCOUNT}. ACCOUNT can be email address or uniqueId of the service account.
availableSecrets

object (Secrets)

Secrets and secret environment variables.
warnings[]

object (Warning)

Output only. Non-fatal problems encountered during the execution of the build.
gitConfig

object (GitConfig)

Optional. Configuration for git operations.
failureInfo

object (FailureInfo)

Output only. Contains information about the build when status=FAILURE.

Methods

approve

 Approves or rejects a pending build.

cancel

 Cancels a build in progress.

create

 Starts a build with the specified configuration.

get

 Returns information about a previously requested build.

list

 Lists previously requested builds.

retry

 Creates a new build based on the specified build.