This page explains how to view information about your Cloud Build
builds using the Google Cloud console, the
gcloud command-line tool, and the
Cloud Build API.
Before you begin
If you want to use the command-line examples in this guide, install the
gcloud command-line tool.
Viewing build results
To view build logs, principals require one of the following IAM roles in addition to the Cloud Build IAM permissions:
If your build logs are in the default Cloud Storage bucket, grant the Project > Viewer role.
If your builds logs are in a user-specified Cloud Storage bucket, grant the Storage Object Viewer role.
For more information about the necessary permissions to view build logs, see Viewing build logs.
In the Cloud console, the Build History menu can show you information about a build's status (such as success or failure), source, results, create time, images, and more.
To view the Build History menu, open the Build History page in the Google Cloud console:
The Build history page is displayed, which shows a list of your recent builds.
To filter builds by region, use the Region drop-down menu at the top of the page to choose the region you would like to filter by.
You can also filter builds using the Filter builds text box at the top of the page, or by entering a query manually.
To view additional columns such as Trigger description and Artifacts, use the column selector.
To view details about a specific build, go the Build History and click on a specified build. The Build details page is displayed, with the Build Summary for your build. The Build Summary includes:
- Build Log, the log of your build.
- Execution Details, the details of your build including your environment variables and substitutions.
- Build Artifacts, the artifacts of your build such as container images, build logs, or binaries.
You can view your the build log or execution details specific to a build step by selecting the step in the Steps table to the left.
gcloud builds list command displays
all your builds.
To view your builds, run the following command:
gcloud builds list
You should see an output similar to the following:
ID CREATE_TIME DURATION SOURCE IMAGES STATUS 3a2055bc-ccbd-4101-9434-d376b88b8940 2018-02-16T18:33:26+00:00 23S gs://gcb-docs-project_cloudbuild/source/1518806004.25-db1e250a7b7f496eb8242bfee5ac308e.tgz gcr.io/gcb-docs-project/quickstart-image (+1 more) SUCCESS 900704ca-7a0c-4569-ac08-884593c19aac 2018-02-16T18:32:32+00:00 gs://gcb-docs-project_cloudbuild/source/1518805951.23-03dd53d16f684c568fa2bb7ff7ebda06.tgz - FAILURE 021f9ede-ddaa-4cfb-8988-60142b015ebd 2018-02-14T15:48:44+00:00 10S gs://gcb-docs-project_cloudbuild/source/1518623322.56-9cd088ffc1e04f5aa6040728772d0c2a.tgz - SUCCESS 8126d538-3c43-4304-a14c-33aceec8cb97 2018-02-14T15:46:13+00:00 10S gs://gcb-docs-project_cloudbuild/source/1518623172.09-327c02585a4e44e782ac97dd80d5a5d5.tgz gcr.io/gcb-docs-project/quickstart-image (+1 more) SUCCESS
To view details about a specific build, run the following command:
gcloud builds describe [BUILD_ID]
where [BUILD_ID] is the ID of the build for which you want to get details.
You should see an output similar to the following:
createTime: '2018-02-22T14:49:54.066666971Z' finishTime: '2018-02-22T14:50:05.463758Z' id: bcdb9c48-d92c-4489-a3cb-08d0f0795a0b images: - gcr.io/gcb-docs-project/quickstart-image logUrl: https://console.cloud.google.com/cloud-build/builds/bcdb9c48-d92c-4489-a3cb-08d0f0795a0b?project=gcb-docs-project logsBucket: gs://404889597380.cloudbuild-logs.googleusercontent.com projectId: gcb-docs-project results: buildStepImages: - sha256:a4363bc75a406c4f8c569b12acdd86ebcf18b6004b4f163e8e6293171462a79d images: - digest: sha256:1b2a237e74589167e4a54a8824f0d03d9f66d3c7d9cd172b36daa5ac42e94eb9 name: gcr.io/gcb-docs-project/quickstart-image pushTiming: endTime: '2018-02-22T14:50:04.731919081Z' startTime: '2018-02-22T14:50:00.874058710Z' - digest: sha256:1b2a237e74589167e4a54a8824f0d03d9f66d3c7d9cd172b36daa5ac42e94eb9 name: gcr.io/gcb-docs-project/quickstart-image:latest pushTiming: endTime: '2018-02-22T14:50:04.731919081Z' startTime: '2018-02-22T14:50:00.874058710Z' source: storageSource: bucket: gcb-docs-project_cloudbuild generation: '1519310993665963' object: source/1519310992.2-8465b08c79e14e89bee09adc8203c163.tgz sourceProvenance: fileHashes: gs://gcb-docs-project_cloudbuild/source/1519310992.2-8465b08c79e14e89bee09adc8203c163.tgz#1519310993665963: fileHash: - value: -aRYrWp2mtfKhHSyWn6KNQ== resolvedStorageSource: bucket: gcb-docs-project_cloudbuild generation: '1519310993665963' object: source/1519310992.2-8465b08c79e14e89bee09adc8203c163.tgz startTime: '2018-02-22T14:49:54.966308841Z' status: SUCCESS steps: - args: - build - --no-cache - -t - gcr.io/gcb-docs-project/quickstart-image - . name: gcr.io/cloud-builders/docker status: SUCCESS timing: endTime: '2018-02-22T14:50:00.813257422Z' startTime: '2018-02-22T14:50:00.102600442Z' timeout: 600s timing: BUILD: endTime: '2018-02-22T14:50:00.873604173Z' startTime: '2018-02-22T14:50:00.102589403Z' FETCHSOURCE: endTime: '2018-02-22T14:50:00.087286880Z' startTime: '2018-02-22T14:49:56.962717504Z' PUSH: endTime: '2018-02-22T14:50:04.731958202Z' startTime: '2018-02-22T14:50:00.874057159Z'
Step status and build status
The following table summarizes the statuses when a build or a step succeeds, times out, or fails:
|Event||Build Status||Step Status|
|Build succeeds||All steps are marked
|Build is cancelled by the user||
|Build times out||
|Step times out||
To view per-step and build status, run the
gcloud builds describe
gcloud builds describe [BUILD_ID]
where [BUILD_ID] is the ID of the build.
The following snippet shows the per-step status from a build with a timed-out step:
status: FAILURE steps: - args: - sleep - '60' id: long sleep name: alpine status: CANCELLED timing: endTime: '2018-02-26T14:09:18.531368493Z' startTime: '2018-02-26T14:09:11.023235026Z' waitFor: - '-' - args: - sleep - '3' id: shorty name: alpine status: SUCCESS timeout: 60s timing: endTime: '2018-02-26T14:09:15.497724138Z' startTime: '2018-02-26T14:09:11.023676903Z' waitFor: - '-' - args: - sleep - '60' name: alpine status: TIMEOUT timeout: 3s timing: endTime: '2018-02-26T14:09:18.527488475Z' startTime: '2018-02-26T14:09:15.497736775Z' waitFor: - shorty - args: - 'false' name: alpine status: QUEUED waitFor: - long sleep timeout: 60s
Filtering build results using queries
To find information for builds that fit specific criteria, supply a query string
in the Filter Builds field in the Build history page in
Google Cloud console. For example, you can query for builds that have failed (that
FAILURE value in the status field), builds that were created after a
certain time, tagged builds, and other such conditions.
Supported fields for queries
You can query for builds based on the values of the following fields:
Fields listed with dot notation (
.) are subfields.
Constructing a query string
Query strings use the general form:
Use dot notation to specify a subfield, such as
!= comparison operators, as well as
<= for fields that have numeric values (such as
You can create compound queries by using the boolean
Common example queries
To query for all successful builds:
To query for all builds that have yet to finish:
status="QUEUED" OR status="WORKING"
To query for builds with a given result image name:
(status="SUCCESS" OR status="FAILURE") AND \ results.images.name="gcr.io/my-project/my-image"
To query for all builds with the tag
To query for builds marked as verified:
To query for builds that come from a source in Cloud Storage (as opposed to a Cloud Source Repository):
To query for builds with a given result digest:
To query for builds started after a specific time and finished before a specific time (UTC timezone):
create_time>"2016-10-12T18:43:49+00:00" AND finish_time<"2016-10-13T18:43:49+00:00"
Filtering build results using tags
You can use tags in your config files, which allows you to organize your builds
into groups and to filter your builds. You can specify strings in tags, such as
Tags have the following limitations:
- Each tag's character limit is 128 characters
- You can define a maximum of 64 tags per build
- Tags can contain letters, numbers, and underscores in any position of your string.
- Tags can contain periods and hyphens in any position except the first position of your string.
To add tags in your build:
In your build config file, add the
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'gcr.io/$PROJECT_ID/cb-demo-img', '.' ] images: - 'gcr.io/$PROJECT_ID/cb-demo-img' tags: - 'test1' - 'test2'
To see tagged builds in your cluster, use the
gcloud builds list. You can filter builds by specifying a single tag or multiple tags.
To filter builds by a single tag, specify the tag as a string in the
tagsfield. The following command lists all builds tagged with
gcloud builds list --filter "tags='test1'"
To filter builds by multiple tags, use "AND", "OR", or "NOT" to list tags. The following command lists all builds tagged with
'test2'and tagged with
gcloud builds list --filter "tags=('test1' OR 'test2') AND 'test3'"
You will see an output similar to the following after running these commands:
ID CREATE_TIME DURATION SOURCE IMAGES STATUS d33a9895-... ... 1M45S gs://... gcr.io/... SUCCESS
Viewing build results for build triggers
The Cloud Build dashboard provides a high-level overview of your most recent builds for each build trigger.
The dashboard is organized by cards, where each card is associated with a build trigger in your repository. If there are multiple triggers created in a single repository, there will be multiple cards. These cards are ordered alphabetically by the name of your repository followed by the name of the trigger. You can also pin any card to the top of the page by hovering over the right side of the card and clicking on the pin icon as indicated in the example below:
Cards are titled by the latest outcomes of the build, such as Successful or Failed. The name of the repository and the trigger name follow the result of the latest outcome. Under the title, the card summarizes results related to your most recent builds.
Viewing the dashboard
The Cloud Build dashboard is populated if you have build triggers set up. To learn more about how to set up build triggers, see Creating and managing build triggers.
To view the Cloud Build dashboard:
Go to the Cloud Build dashboard page:
Select your project from the drop-down menu.
You will see the Cloud Build dashboard listing recent builds for your builds triggers.
The Cloud Build dashboard displays the following information:
Latest build: The date and time of your most recent build.
Duration: The duration of your most recent build, in
Source: Links to your connected source repository. Your source repository can either be a Cloud Source Repository, a GitHub repository, or a Bitbucket repository.
Commit: Links to the commit that was used for your build.
Failed Step: The failed step that resulted in the build failure, if your most recent build has failed.
If your most recent build has failed, Failed step will link to the step that caused the failure in your build log.
Build History: A bar chart representing the build duration for your 20 most recent builds. You can hover over each bar in the bar chart to view information about each individual build.
Average Duration: The average runtime of your 20 most recent builds, not including builds that are still running.
If the average duration of your build time exceeds 10 minutes and the machine type you specified for your build is
N1_HIGHCPU_8, you will see the IMPROVE SPEED button. You can click on IMPROVE SPEED to view recommendations on how to improve the speed of your build. To learn more, see Best practices for speeding up builds.
Pass - Fail %: The average pass/fail ratio of your 20 most recent builds.
To filter cards on your dashboard, click the Filter triggers option at the top of the Cloud Build dashboard page:
You can filter cards by:
- Trigger source: the name of your source repository.
- Trigger name: the name of your trigger.
- Trigger description: the description of your trigger.
- Learn how to store and view build logs.
- Learn how to configure notifications using the Slack notifier.
- Learn how to configure notifications using the SMTP notifier.
- Learn how to troubleshoot build errors.