Store and view build logs

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 send build logs

You can configure Cloud Build to send build logs to a bucket in Cloud Storage, a bucket in Cloud Logging, or both.

• If you want to control the retention period of your stored build logs, then send them to Cloud Logging. Cloud Logging also provides more options to search a bucket for specific build logs.

• In some cases, there is a delay between when a build log is generated and when Logging receives it. Sending your build logs to a bucket in Cloud Storage may reduce that latency.

Both Cloud Storage and Logging let you store logs in either a default Google-created bucket or in a custom user-created bucket. Default buckets let you view logs stored in the bucket, but don't let you change anything about the bucket. If you require full control over the bucket that you use for build log storage, then send your logs to a user-created bucket.

Store build logs in default buckets

Cloud Logging and Cloud Storage both have default buckets where you can store your build logs. These buckets are created and owned by Google, and can receive logs from multiple regions. To send your build logs to one of these buckets, configure the LoggingMode of your build config file with one of the following values:

• GCS_ONLY: Logs are stored in the default Cloud Storage bucket.

• CLOUD_LOGGING_ONLY: Logs are stored in the default Logging bucket.

• LEGACY: Logs are stored in both default buckets.

The default Logging bucket has a 30-day retention policy for stored logs. To set a custom retention policy for build logs stored in Logging, store your build logs in a custom bucket.

The default Cloud Storage bucket has no retention policy.

Store build logs in a user-owned and region-specific Cloud Storage bucket

If you send build logs to the default Cloud Storage bucket, then Cloud Build stores them in a Google-specified region that might be different from the location where you run a build. However, you can also configure your build so that Cloud Build sends build logs to a user-owned Cloud Storage bucket in the same region that you run your build. This configuration gives you more control over your build log data location, which can help you comply with data residency requirements.

Note: You will incur a cost for storing logs in your own bucket. For pricing details, see Cloud Storage pricing.

Grant IAM permissions:

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, then that service account has the necessary IAM permissions by default. You don't have to grant any additional permissions. Otherwise, do the following:

To get the permissions that you need to store build logs in a user-owned and region-specific bucket, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the service account used for your build. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Configure the region-specific Cloud Storage bucket:

1. In your build config file, add the defaultLogsBucketBehavior option and set its value to REGIONAL_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"
       }
   }
   

2. 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 bucket in the region where you are executing your build, then stores the build logs in this bucket. Further builds in the same project and region will use the existing bucket as long as REGIONAL_USER_OWNED_BUCKET is active. This bucket is user-owned, so you can configure it as if it were a user-created bucket.

If you set the REGIONAL_USER_OWNED_BUCKET option and then create builds in multiple regions, then Cloud Build creates multiple buckets for your build logs.

Region-specific default Cloud Storage buckets have no retention policy. However, you can automate the deletion of build logs from your bucket by configuring an object lifecycle rule.

Store build logs in user-created buckets

User-created buckets give you greater control over managing and configuring your log buckets.

Store build logs in a user-created Cloud Logging bucket

User-created Logging buckets let you adjust the retention period of stored build logs. To store your build logs in a user-created bucket in Logging, do the following:

Grant IAM permissions:

To get the permissions that you need to store build logs in a user-created Cloud Logging bucket, ask your administrator to grant you the Logs Configuration Writer (roles/logging.configWriter) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Configure the Logging bucket:

1. Create a bucket and set a value for the Retention period field.

2. Create a sink to route your build logs to your new bucket:

   1. Enter the following for your sink's build inclusion filter:

      logName = "projects/PROJECT_ID/logs/cloudbuild"
      

      Replace PROJECT-ID with your Google Cloud project ID.

   2. (Optional) To prevent your logs from going to the default Logging bucket, follow the example in Stop storing log entries in log buckets.

Store build logs in a user-created Cloud Storage bucket

To store your build logs in a user-created Cloud Storage bucket, do the following:

Grant IAM permissions:

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. Otherwise, do the following:

To get the permissions that you need to store build logs in a user-created Cloud Storage bucket, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the service account used for your build. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Configure the Cloud Storage bucket:

1. In your Google Cloud project, create a Cloud Storage bucket with no retention policy set to store your build logs.

2. 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 named mylogsbucket:

   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"
          }
       }
   

3. 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.

Precedence between logs settings

If you define a user-created Cloud Storage bucket in logsBucket, then Cloud Build sends your build logs to the user-created bucket instead of the default Cloud Storage bucket.

If you are adding the defaultLogsBucketBehavior option to an existing build config file and you have previously configured logging or logsBucket options, then 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 file, Cloud Build sets logging: LEGACY and stores build logs in the default Cloud Storage bucket. Setting defaultLogsBucketBehavior to REGIONAL_USER_OWNED_BUCKET overrides logging: LEGACY.

View build logs

To view your build logs, do the following:

Grant IAM permissions:

To get the permissions that you need to view build logs in Cloud Storage or Logging, ask your administrator to grant you the following IAM roles on the service account used for your build:

• View build logs in a user-created or user-owned Cloud Storage bucket:
  • Storage Object Viewer (roles/storage.objectViewer) - the principals who want to view build logs
  • Logs View Accessor (roles/logging.viewAccessor) - the principals who want to view build logs
• View build logs in the default Cloud Storage bucket: Viewer (roles/viewer) - the project where the build is configured
• View build logs in Logging: Logs Viewer (roles/logging.viewer) - the principals who want to view build logs

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Note: Granting a project the Owner (roles/owner) or Editor (roles/editor) roles also allows principals to view build logs from default buckets. However, to view build logs in the default Cloud Storage bucket, we recommend using the Viewer role so that your role assignment complies with the security principle of least privilege.

Note: To avoid granting the basic Viewer role, store build logs in a user-specified bucket. We recommend this practice especially if your builds are invoked by triggers and you only want to grant access to invoke builds and view build progress.

View build logs in Google Cloud:

Console

1. Open the Cloud Build page in the Google Cloud console.

   Open the Cloud Build page

2. Select your project and click Open.

3. In the Region drop-down menu, select the region for your build.

4. In the Build history page, select a particular build.

5. In the Build details page, under Steps, click Build summary to view build logs for your entire build or select a build step to view build logs for that step.

6. If your logs are stored in Logging, in the Build log panel, then 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

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, then you can view your build logs in GitHub and GitHub Enterprise.

To view build logs in GitHub and GitHub Enterprise, do the following:

1. Navigate to the repository associated with your trigger.

2. Navigate to your list of commits.

3. Locate the row of the commit you want to view build logs for.

4. Click the result icon in the row of your commit.

   You will see a list of checks associated with your commit.

5. Click 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.

Note: The service account you used for the trigger must include the roles/logging.viewer role to be able to send the build logs to GitHub.

Delete build logs and buckets

To get the permissions that you need to delete build logs and buckets in Cloud Storage, ask your administrator to grant you the following IAM roles on the service account used for your build:

• Delete build logs in a user-created or user-owned Cloud Storage bucket: Storage Admin (roles/storage.admin) - the user or service account deleting build logs
• Delete a user-created or user-owned Cloud Storage bucket: Storage Admin (roles/storage.admin) - the user or service account deleting buckets
• Delete a user-created Logging bucket: Logs Configuration Writer (roles/logging.configWriter) - your project

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

To delete build logs in a user-created or user-owned Cloud Storage bucket, follow the instructions in Deleting objects in the Cloud Storage documentation.

To delete a user-created or user-owned Cloud Storage bucket, follow the instructions in Deleting buckets in the Cloud Storage documentation.

To delete a user-created Logging bucket, follow the instructions in Delete a bucket in the Logging documentation.

What's next

• Learn about audit logs created by Cloud Build.
• Learn how to view build results.
• Learn more about Cloud Build IAM permissions.