REST Resource: projects.locations.backends.builds

Resource: Build

A single build for a backend, at a specific point codebase reference tag and point in time. Encapsulates several resources, including an Artifact Registry container image, a Cloud Build invocation that built the image, and the Cloud Run revision that uses that image.

JSON representation 
{
  "name": string,
  "displayName": string,
  "config": {
    object (Build.Config)
  },
  "source": {
    object (BuildSource)
  },
  "state": enum (Build.State),
  "image": string,
  "buildLogsUri": string,
  "environment": string,
  "errors": [
    {
      object (Build.Error)
    }
  ],
  "reconciling": boolean,
  "createTime": string,
  "updateTime": string,
  "deleteTime": string,
  "labels": {
    string: string,
    ...
  },
  "annotations": {
    string: string,
    ...
  },
  "uid": string,
  "etag": string
}
Fields
name

string

Identifier. The resource name of the build.

Format:

projects/{project}/locations/{locationId}/backends/{backendId}/builds/{buildId}.
displayName

string

Optional. Human-readable name. 63 character limit.
config

object (Build.Config)

Optional. Additional configuration of the service.
source

object (BuildSource)

Required. Immutable. The source for the build.
state

enum (Build.State)

Output only. The state of the build.
image

string

Output only. The Artifact Registry container image URI, used by the Cloud Run revision for this build.
buildLogsUri

string

Output only. The location of the Cloud Build logs for the build process.
environment

string

Output only. The environment name of the backend when this build was created.
errors[]

object (Build.Error)

Output only. A list of all errors that occurred during an App Hosting build.
reconciling

boolean

Output only. A field that, if true, indicates that the build has an ongoing LRO.
createTime

string (Timestamp format)

Output only. Time at which the build was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Time at which the build was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
deleteTime

string (Timestamp format)

Output only. Time at which the build was deleted.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
labels

map (key: string, value: string)

Optional. Unstructured key value map that can be used to organize and categorize objects.

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

map (key: string, value: string)

Optional. Unstructured key value map that may be set by external tools to store and arbitrary metadata. They are not queryable and should be preserved when modifying objects.

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

string

Output only. System-assigned, unique identifier.
etag

string

Output only. Server-computed checksum based on other values; may be sent on update or delete to ensure operation is done on expected resource.

Build.Config

Additional configuration of the backend for this build.

JSON representation 
{
  "runConfig": {
    object (RunConfig)
  },
  "effectiveEnv": [
    {
      object (EnvironmentVariable)
    }
  ]
}
Fields
runConfig

object (RunConfig)

Optional. Additional configuration of the Cloud Run service.
effectiveEnv[]

object (EnvironmentVariable)

Output only. [OUTPUT_ONLY] This field represents all environment variables employed during both the build and runtime. This list reflects the result of merging variables from all sources (Backend.override_env, Build.Config.env, YAML, defaults, system). Each variable includes its origin

RunConfig

Configuration applied to the Cloud Run service.

JSON representation 
{
  "cpu": number,
  "memoryMib": integer,
  "concurrency": integer,
  "maxInstances": integer,
  "minInstances": integer
}
Fields
cpu

number

Optional. Number of CPUs used for each serving instance.

By default, cpu defaults to the Cloud Run's default of 1.0.

CPU can be set to value 1, 2, 4, 6, or 8 CPUs, and for less than 1 CPU, a value from 0.08 to less than 1.00, in increments of 0.01.

If you set a value of less than 1 CPU, you must set concurrency to 1, and CPU will only be allocated during request processing.

Increasing CPUs limit may require increase in memory limits:

  • 4 CPUs: at least 2 GiB
  • 6 CPUs: at least 4 GiB
  • 8 CPUs: at least 4 GiB
memoryMib

integer

Optional. Amount of memory allocated for each serving instance in MiB.

By default, memory defaults to the Cloud Run's default where each instance is allocated 512 MiB of memory.

Memory can be set to any integer value between 128 to 32768.

Increasing memory limit may require increase in CPUs limits:

  • Over 4 GiB: at least 2 CPUs
  • Over 8 GiB: at least 4 CPUs
  • Over 16 GiB: at least 6 CPUs
  • Over 24 GiB: at least 8 CPUs
concurrency

integer

Optional. Maximum number of requests that each Cloud Run instance can receive.

By default, each instance can receive Cloud Run's default of up to 80 requests at the same time.

Concurrency can be set to any integer value up to 1000.
maxInstances

integer

Optional. Number of Cloud Run instances to maintain at maximum for each revision.

By default, each Cloud Run service scales out to Cloud Run's default of a maximum of 100 instances. The maximum maxInstances limit is based on your quota. See https://cloud.google.com/run/docs/configuring/max-instances#limits.
minInstances

integer

Optional. Number of Cloud Run instances to maintain at minimum for each Cloud Run Service.

By default, there are no minimum.

Even if the service splits traffic across multiple revisions, the total number of instances for a service will be capped at this value.

EnvironmentVariable

Environment variables for this build.

JSON representation 
{
  "variable": string,
  "availability": [
    enum (EnvironmentVariable.Availability)
  ],
  "origin": enum (EnvironmentVariable.Origin),
  "originFileName": string,

  // Union field source can be only one of the following:
  "value": string,
  "secret": string
  // End of list of possible types for union field source.
}
Fields
variable

string

Required. The name of the environment variable. The environment variables reserved by Cloud Run should not be set. Additionally, variable names cannot start with "X_FIREBASE_".
availability[]

enum (EnvironmentVariable.Availability)

Optional. Where this variable should be made available. If left unspecified, will be available in both BUILD and BACKEND.
origin

enum (EnvironmentVariable.Origin)

Output only. The high-level origin category of the environment variable.
originFileName

string

Output only. Specific detail about the source. For APPHOSTING_YAML origins, this will contain the exact filename, such as "apphosting.yaml" or "apphosting.staging.yaml".
Union field source. The source of a variable's value. source can be only one of the following:
value

string

A plaintext value. This value is encrypted at rest, but all project readers can view the value when reading your backend configuration.
secret

string

A fully qualified secret version. The value of the secret will be accessed once while building the application and once per cold start of the container at runtime. The service account used by Cloud Build and by Cloud Run must each have the secretmanager.versions.access permission on the secret.

EnvironmentVariable.Availability

Represents where the variable is available.

Enums
AVAILABILITY_UNSPECIFIED The default value, unspecified, which is unused.
BUILD This value is available when creating a Build from source code.
RUNTIME This value is available at runtime within Cloud Run.

EnvironmentVariable.Origin

Represents the origin category of an environment variable.

Enums
ORIGIN_UNSPECIFIED Source is unspecified.
BACKEND_OVERRIDES Variable was set on the backend resource (e.g. via API or Console). Represents variables from Backend.override_env
BUILD_CONFIG Variable was provided specifically for the build upon creation via the Build.Config.env field. Only used for pre-built images.
APPHOSTING_YAML Variable is defined in apphosting.yaml file.
FIREBASE_SYSTEM Variable is defined provided by the firebase platform.

BuildSource

The source for the build.

JSON representation 
{

  // Union field source can be only one of the following:
  "codebase": {
    object (BuildSource.CodebaseSource)
  },
  "container": {
    object (BuildSource.ContainerSource)
  },
  "archive": {
    object (BuildSource.ArchiveSource)
  }
  // End of list of possible types for union field source.
}
Fields
Union field source. The input source for the build. Typically will reference a commit in a source repository. May also reference a container image. source can be only one of the following:
codebase

object (BuildSource.CodebaseSource)

A codebase source.
container

object (BuildSource.ContainerSource)

An Artifact Registry container image source.
archive

object (BuildSource.ArchiveSource)

An archive source.

BuildSource.CodebaseSource

A codebase source, representing the state of the codebase that the build will be created at.

JSON representation 
{
  "displayName": string,
  "repository": string,
  "hash": string,
  "commitMessage": string,
  "uri": string,
  "author": {
    object (BuildSource.CodebaseSource.UserMetadata)
  },
  "commitTime": string,

  // Union field reference can be only one of the following:
  "branch": string,
  "commit": string
  // End of list of possible types for union field reference.
}
Fields
displayName

string

Output only. The human-friendly name to use for this Codebase when displaying a build. We use the first eight characters of the SHA-1 hash for GitHub.com.
repository

string

Output only. The resource name for the Developer Connect gitRepositoryLink used for this build, in the format:

projects/{project}/locations/{location}/connections/{connection}/gitRepositoryLinks/{repositoryLink}
hash

string

Output only. The full SHA-1 hash of a Git commit, if available.
commitMessage

string

Output only. The message of a codebase change.
uri

string

Output only. A URI linking to the codebase on an hosting provider's website. May not be valid if the commit has been rebased or force-pushed out of existence in the linked repository.
author

object (BuildSource.CodebaseSource.UserMetadata)

Output only. The author contained in the metadata of a version control change.
commitTime

string (Timestamp format)

Output only. The time the change was made.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
Union field reference. The reference to the codebase to build from. reference can be only one of the following:
branch

string

The branch in the codebase to build from, using the latest commit.
commit

string

The commit in the codebase to build from.

BuildSource.CodebaseSource.UserMetadata

Version control metadata for a user associated with a resolved codebase. Currently assumes a Git user.

JSON representation 
{
  "displayName": string,
  "email": string,
  "imageUri": string
}
Fields
displayName

string

Output only. The 'name' field in a Git user's git.config. Required by Git.
email

string

Output only. The 'email' field in a Git user's git.config, if available.
imageUri

string

Output only. The URI of an image file associated with the user's account in an external source control provider, if available.

BuildSource.ContainerSource

The URI of an Artifact Registry container image to use as the build source.

JSON representation 
{
  "image": string
}
Fields
image

string

Required. A URI representing a container for the backend to use.

BuildSource.ArchiveSource

The URI of an storage archive or a signed URL to use as the build source.

JSON representation 
{
  "rootDirectory": string,
  "author": {
    object (BuildSource.ArchiveSource.SourceUserMetadata)
  },
  "description": string,

  // Union field uri can be only one of the following:
  "userStorageUri": string,
  "externalSignedUri": string
  // End of list of possible types for union field uri.
}
Fields
rootDirectory

string

Optional. The directory relative to the root of the archive to use as the root for the deployed web app. Defaults to use the root of the repository if not provided. If deploying a monorepo, this should be the directory that contains the package.json or apphosting.yaml file.
author
(deprecated)

object (BuildSource.ArchiveSource.SourceUserMetadata)

Optional. Deprecated: Not used.

The author contained in the metadata of a version control change.
description

string

Optional. An optional message that describes the uploaded version of the source code.
Union field uri. The URI of the archive to use as the build source. uri can be only one of the following:
userStorageUri

string

URI to an archive in Cloud Storage. The object must be a zipped (.zip) or gzipped archive file (.tar.gz) containing source to deploy.
externalSignedUri

string

Signed URL to an archive in a storage bucket.

BuildSource.ArchiveSource.SourceUserMetadata

Deprecated: Not used.

Metadata for the user who started the build.

JSON representation 
{
  "displayName": string,
  "email": string,
  "imageUri": string
}
Fields
displayName
(deprecated)

string

Output only. Deprecated: Not used.

The user-chosen displayname. May be empty.
email
(deprecated)

string

Output only. Deprecated: Not used.

The account email linked to the EUC that created the build. May be a service account or other robot account.
imageUri
(deprecated)

string

Output only. Deprecated: Not used.

The URI of a profile photo associated with the user who created the build.

Build.State

The state of the build.

Enums
STATE_UNSPECIFIED The build is in an unknown state.
BUILDING The build is building.
BUILT The build has completed and is awaiting the next step. This may move to DEPLOYING once App Hosting starts to set up infrastructure.
DEPLOYING The infrastructure for this build is being set up.
READY The infrastructure for this build is ready. The build may or may not be serving traffic - see Backend.traffic for the current state, or Backend.traffic_statuses for the desired state.
FAILED The build has failed.
SKIPPED The build was skipped.
EXPIRED The build has expired and may not be reused.

Build.Error

The container for the rpc status and source for any errors found during the build process.

JSON representation 
{
  "error": {
    object (Status)
  },
  "errorSource": enum (Build.ErrorSource),
  "cloudResource": string
}
Fields
error

object (Status)

Output only. A status and (human readable) error message for the build, if in a FAILED state.
errorSource

enum (Build.ErrorSource)

Output only. The source of the error for the build, if in a FAILED state.
cloudResource

string

Output only. Resource link

Build.ErrorSource

Deprecated: Use errors instead. The source of the error for the build, if in a FAILED state.

Enums
ERROR_SOURCE_UNSPECIFIED Indicates that generic error occurred outside of the Cloud Build or Cloud Run processes, such as a pre-empted or user-canceled App Hosting Build.
CLOUD_BUILD Indicates that the build failed during the Cloud Build process, such as a build timeout.
CLOUD_RUN Indicates that the build failed during the Cloud Run process, such as a service creation failure.

Methods

create

 Creates a new build for a backend.

delete

 Deletes a single build.

get

 Gets information about a build.

list

 Lists builds in a given project, location, and backend.