Store and manage 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 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:

1. In your build config file, set the value of logging to CLOUD_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"
     }
   }
   

2. Use the build config file to start a build using the command line, the API or triggers.

Map build log fields to log entry fields

You can configure the JSON of your build logs so that specified build log fields are mapped to LogEntry fields when the build log is sent to Logging. For example, if your build log contains a message, then the message appears in either textPayload or jsonPayload.message in the resulting log entry. Build log fields that aren't mappable appear in the log entry jsonPayload.

To enable field mapping on your build logs, set the BuildOptions field enableStructuredLogging to TRUE.

The following table shows build log fields that map to a log entry field:

BuildLog Field (JSON)	LogEntry Field	Description	Notes
message	textPayload or jsonPayload.message	Lets users set the log message	Must be a string. If the build log contains only mappable fields, then the message appears in textPayload. Otherwise, the message appears in jsonPayload.message. If the build log contains multiple steps, then the step identifier appears at the beginning of the message.
severity	severity	Lets users set the log severity.	Must be an enum of LogSeverity.

The following build log fields can't be mapped and will be dropped from the log entry if they appear in a build log:

• httpRequest
• logging.googleapis.com/insertId
• logging.googleapis.com/labels
• logging.googleapis.com/operation
• logging.googleapis.com/sourceLocation
• logging.googleapis.com/spanId
• logging.googleapis.com/trace
• logging.googleapis.com/trace_sampled
• time
• timestamp
• timestampSeconds
• timestampNanos

All other build log field will appear as part of the log entry's jsonPayload.

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:

  1. Open the IAM page in the project where your Cloud Storage bucket is located:

     Open the IAM page

  2. Click Grant access.

  3. Enter the email address of the service account.

  4. Select Cloud Storage > Storage Admin.

  5. Click Save.

To specify a Cloud Storage bucket to store build logs:

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.

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:

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

2. In your build config, 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"
       }
   }
   

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

  1. Open the IAM page:

     Open the IAM page

  2. Select your project and click Open.

  3. In the permissions table, locate the email ID of the principal and click the pencil icon.

  4. Select Logging > Logs Viewer role.

  5. Click Save.

• If your build logs are in the default Google-created Cloud Storage bucket, then grant the Project Viewer role on the project where the build is configured to principals who want to view build logs:

  1. Open the IAM page:

     Open the IAM page

  2. Select your project and click Open.

  3. In the permissions table, locate the email ID of the principal and click the pencil icon.

  4. Select Project > Viewer role.

  5. Click Save.

  Note: Project Owner and Project Editor roles also allow principals to view build logs from the default Cloud Storage bucket. This is because the Owner role includes the permissions in the Editor role, and the Editor role includes the permissions in the Viewer role. To view build logs in the default Cloud Storage bucket, we recommend granting the Project Viewer role to comply with the security principle of least privilege.
  Note: To avoid granting the basic Project Viewer role, store build logs in a user-specified bucket. We recommend this practice especially if your builds are invoked using triggers and you only want to grant access to invoke builds and view build progress.

  If your build logs are in a user-created or user-owned Cloud Storage bucket, then grant the Storage Object Viewer role to principals who want to view build logs:

  1. Open the IAM page:

     Open the IAM page

  2. Select your project and click Open.

  3. In the permissions table, locate the email ID of the principal and click the pencil icon.

  4. Select Cloud Storage > Storage Object Viewer role.

  5. Click Save.

To view build logs in Cloud Build:

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, click a particular build.

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

   

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

To view build logs in GitHub and GitHub Enterprise:

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

You cannot delete build logs in the Google-created logs bucket.

To delete build logs in a user-created logs bucket:

1. Grant the Storage Object Admin role to the user or the service account deleting logs.

2. Delete the build logs using the instructions to delete Cloud Storage objects in Deleting objects.

To delete the user-created logs bucket:

1. Grant the Storage Admin role to the user or the service account deleting the logs bucket.

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