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:

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', 'gcr.io/myproject/myimage', '.']
options:
  logging: CLOUD_LOGGING_ONLY

JSON

{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "build",
      "-t",
      "gcr.io/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 Cloud Build service account or the user-specified service account:

If your Cloud Storage bucket and Cloud Build are in the same Cloud project and you're using the Cloud Build service account, your Cloud Build service account has the necessary IAM permissions by default. You do not have to grant any additional permissions.
If your Cloud Storage bucket and Cloud Build are in the same Cloud project and you're using a user-specified service account, grant the Storage Admin role to the service account. For instructions on granting a role to a service account, see Granting roles on the project.
If your Cloud Storage bucket and Cloud Build are in different Cloud projects, grant the Storage Admin role to the Cloud Build service account:
1. Open the IAM page:
  
  Open the IAM page
2. Select the project in which you're running builds using Cloud Build.
3. In the permissions table, locate the email address ending with @cloudbuild.gserviceaccount.com and note it down. This is your Cloud Build service account.
4. Open the IAM page in the project where your Cloud Storage bucket is located:
  
  Open the IAM page
5. Click Grant access.
6. Enter the email address of the Cloud Build service account.
7. Select Cloud Storage > Storage Admin.
8. Click Save.

To specify a Cloud Storage bucket to store build logs:

In your 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 named mylogsbucket:

YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: [ 'build', '-t', 'gcr.io/myproject/myimage', '.' ]
    logsBucket: 'gs://mylogsbucket'
    options:
      logging: GCS_ONLY

JSON

    {
      "steps": [
       {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
           "build",
           "-t",
           "gcr.io/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 service account, your Cloud Build service account has the necessary IAM permissions by default. You do not have to grant any additional permissions.
- If you're using a user-specified service account, grant the Storage Admin role to the service account. 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 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"
    }
}

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:
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 on 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, 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 on 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. But to view build logs in the default Cloud Storage bucket, we recommend granting 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 via 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, 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 on the pencil icon.
4. Select Cloud Storage > Storage Object Viewer role.
5. Click Save.

To view build logs in Cloud Build:

Console

Open the Cloud Build page in the Google Cloud console.

Open the Cloud Build page
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 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.