Store and view build logs

Set up your build config file to to store your build logs in log buckets so that you can group and analyze them using Cloud Logging and Cloud Storage tools. Configuring your build log storage allows for greater control over the storage and analysis of your logs. If you leave your build log storage settings undefined, then Cloud Build stores them in a Google Cloud-owned bucket with fewer options for build log analysis.

This page describes how to store build logs in different types of buckets, and how to view and delete stored logs.

Before you begin

Ensure that you are familiar with the build config file options for configuring build log storage and how bucket ownership impacts log accessibility. For more information, see Build log storage options.

Store build logs in user-created buckets

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

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

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 the account or service account for 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 build 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 build logs in the Cloud Storage bucket you specified in the build config file.

Store build logs in region-specific Cloud Storage buckets

You can configure your build so that Cloud Build sends build logs to a user-owned Cloud Storage bucket in the same region as your build. Aligning the regions of your build and build log storage bucket can help you comply with data residency requirements.

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 create builds in multiple regions, then Cloud Build creates a Cloud Storage bucket for each unique region.

You can also use a user-created bucket if you need to align your build's region and log bucket. In this case, you can either select an existing user-created bucket that has the same region, or create one. If you want to create one, then follow the steps to Store build logs in user-created buckets and ensure that your user-created bucket has the same region as your build.

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: You can grant the Owner (roles/owner) or Editor (roles/Editor) roles at the project level to allow principals to view build logs from Cloud Build-created and user-owned buckets. However, we recommend using the Viewer role in this case so that your role assignment complies with the security principle of least privilege. If you don't want to grant the basic Viewer role, use user-created buckets instead. 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 build 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 with the gcloud CLI or the Cloud Build API 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.