When you run builds, Cloud Build collects and stores your build logs. This page explains how to store, view, and delete build logs.
Choose where to store build logs
You can configure Cloud Build to store build logs in Cloud Logging
or in Cloud Storage by including the logging
field in your Cloud Build configuration file.
If you don't specify a logging
field in your build config file, Cloud Build
stores build logs in both Logging and Cloud Storage.
The following steps store build logs only in Logging:
In your build config file, set the value of
logging
toCLOUD_LOGGING_ONLY
:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.'] options: logging: CLOUD_LOGGING_ONLY
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "us-east1-docker.pkg.dev/myproject/myimage", "." ] } ], "options": { "logging": "CLOUD_LOGGING_ONLY" } }
Use the build config file to start a build using the command line, the API or triggers.
Store build logs in the default Google-created bucket
By default, Cloud Build stores your build logs in a Google-created Cloud Storage bucket. You can view build logs stored in the Google-created Cloud Storage bucket, but you cannot make any other changes to it. If you require full control over your logs bucket, store the logs in a user-created Cloud Storage bucket.
Store build logs in a user-created bucket
IAM permissions:
To store build logs in your own Cloud Storage bucket, you must first grant the necessary IAM permissions to the service account you are using for the build:
If your Cloud Storage bucket and Cloud Build are in the same Google Cloud project and you're using the Cloud Build legacy service account, your Cloud Build legacy service account has the necessary IAM permissions by default. You don't have to grant any additional permissions.
In any other case, grant the Storage Admin role to the service account you are using for the build:
Open the IAM page in the project where your Cloud Storage bucket is located:
Click Grant access.
Enter the email address of the service account.
Select Cloud Storage > Storage Admin.
Click Save.
To specify a Cloud Storage bucket to store build logs:
In your Google Cloud project, create a Cloud Storage bucket with no retention policy set to store your build logs.
In your build config file, add a
logsBucket
field pointing to the Cloud Storage bucket that you created to store build logs. The following example build config file contains instructions to build a container image and store the build logs in a bucket namedmylogsbucket
:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.' ] logsBucket: 'gs://mylogsbucket' options: logging: GCS_ONLY
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "us-east1-docker.pkg.dev/myproject/myimage", "." ] } ], "logsBucket": "gs://mylogsbucket", "options": { "logging": "GCS_ONLY" } }
Use the build config file to start a build using the command line, the API or triggers.
When the build completes, Cloud Build stores the logs in the Cloud Storage bucket you specified in the build config file.
Store build logs in a user-owned and regionalized bucket
By default, Cloud Build stores build logs in a Google-specified region that may be different from the location where you run a build. The defaultLogsBucketBehavior
option lets you configure Cloud Build to use a default logs bucket within your own project and in the same region as the build. This configuration gives you more control over your logs data location, which can help you comply with data residency requirements.
You will incur a cost for storing logs in your own project. For pricing details, see Cloud Storage pricing.
Configure Cloud Build to use regionalized, user-owned logs:
Grant necessary IAM permissions.
If you're using the Cloud Build legacy service account, your Cloud Build legacy service account has the necessary IAM permissions by default. You don't have to grant any additional permissions.
For other service accounts, grant the Storage Admin role to the service account you are using for the build. For instructions on granting a role to a service account, see Granting roles on the project.
In your build config, add the
defaultLogsBucketBehavior
option and set its value toREGIONAL_USER_OWNED_BUCKET
:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ] options: defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "us-central1-docker.pkg.dev/myproject/myrepo/myimage", "." ] } ], "options": { "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET" } }
Use the build config file to start a build using the command line, the API or triggers.
When you run your build, Cloud Build creates the new logs bucket in the region where you are executing your build, then stores the build logs this bucket. Subsequent builds in the same project and region will utilize the existing bucket by default.
If you set the defaultLogsBucketBehavior
option and then create builds in multiple regions, Cloud Build creates multiple buckets for your build logs.
Regionalized build logs stored in your own project have no retention policy. This setting is immutable.
Precedence between logs settings
If you are adding the defaultLogsBucketBehavior
option to an existing build config file and you have previously configured logging
or logsBucket
options, we recommend that you delete those settings to prevent conflict between settings.
Specifically, the defaultLogsBucketBehavior
won't work if you have configured:
logging: CLOUD_LOGGING_ONLY
to store your build logs in Cloud Logging.logging: NONE
to turn off logging.
When you run a build with no logging options set in your build config, Cloud Build sets logging: LEGACY
and stores logs in the default Google-created Cloud Storage bucket. If you add defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET
, this option overrides logging: LEGACY
.
View build logs
IAM permissions:
If your build logs are in Logging, grant the Logs Viewer role on the project where the build is configured to principals who want to view build logs:
Open the IAM page:
Select your project and click Open.
In the permissions table, locate the email ID of the principal and click on the pencil icon.
Select Logging > Logs Viewer role.
Click Save.
If your build logs are in the default Google-created Cloud Storage bucket, grant the Project Viewer role on the project where the build is configured to principals who want to view build logs:
Open the IAM page:
Select your project and click Open.
In the permissions table, locate the email ID of the principal and click on the pencil icon.
Select Project > Viewer role.
Click Save.
If your build logs are in a user-created or user-owned Cloud Storage bucket, grant the Storage Object Viewer role to principals who want to view build logs:
Open the IAM page:
Select your project and click Open.
In the permissions table, locate the email ID of the principal and click on the pencil icon.
Select Cloud Storage > Storage Object Viewer role.
Click Save.
To view build logs in Cloud Build:
Console
Open the Cloud Build page in the Google Cloud console.
Select your project and click Open.
In the Region drop-down menu, select the region for your build.
In the Build history page, click on a particular build.
In the Build details page, under Steps, click on Build summary to view build logs for your entire build or click on a build step to view build logs for that step.
If your logs are stored in Logging, in the Build log panel, click the
icon to view the logs in Logs Explorer.
gcloud
Run the gcloud builds log
command where
build-id is the ID of the build for which you want to
get build logs. The build ID is displayed at the end of the build submission
process when you run gcloud builds submit
, or in the ID column when you run
gcloud builds list
.
gcloud builds log build-id
To view build logs in GitHub and GitHub Enterprise:
If you create a GitHub or GitHub Enterprise trigger and
specified --include-logs-with-status
as an option,
you are able to view your build logs in GitHub and GitHub
Enterprise.
To view build logs in GitHub and GitHub Enterprise:
Navigate to the repository associated with your trigger.
Navigate to your list of commits.
Locate the row of the commit you want to view build logs for.
Click on the result icon in the row of your commit.
You will see a list of checks associated with your commit.
Click on Details for the row you want to view build logs for.
You will see the Summary page associated with your commit. If you have created a trigger using the
--include-logs-with-status
flag, you will see your build logs displayed under the Details section of the page.
Delete build logs
You cannot delete build logs in the Google-created logs bucket.
To delete build logs in a user-created logs bucket:
Grant the Storage Object Admin role to the user or the service account deleting logs.
Delete the build logs using the instructions to delete Cloud Storage objects in Deleting objects.
To delete the user-created logs bucket:
Grant the Storage Admin role to the user or the service account deleting the logs bucket.
Delete the logs bucket using the instructions to delete a bucket in Deleting buckets.
What's next
- Learn about audit logs created by Cloud Build.
- Learn how to view build results.
- Learn more about Cloud Build IAM permissions.