Configuring user-specified service accounts

This page explains how to configure user-specified service accounts for builds.

By default, Cloud Build uses a special service account to execute builds on your behalf. This service account is called the Cloud Build service account and it is created automatically when you enable the Cloud Build API in a Google Cloud project. This service account has a number of permissions by default such as the ability to update builds or write logs.

Instead of using the default Cloud Build service account, you can specify your own service account to execute builds on your behalf. You can specify any number of service accounts per project. Maintaining multiple service accounts enables you to grant different permissions to these service accounts depending on the tasks they perform. For example, you can use one service account for building and pushing images to the Container Registry and a different service account for building and pushing images to Artifact Registry.

Before you begin

  • Enable the Cloud Build and IAM APIs.

    Enable the APIs

  • To use the command-line examples in this guide, install and configure the Cloud SDK.

  • Make sure you've created the service account you want to use. You must create the account in the same Cloud project where you're running builds.

Setting up build logs

To specify your own service account for builds, you must store your build logs either in Cloud Logging or in a user-created Cloud Storage bucket. You cannot store your logs in the default logs bucket.

Required IAM permissions

For instructions on granting IAM roles to a service account, see Configuring access to resources.

Running builds from the command line

  1. In your project root directory, create Cloud Build build config file named cloudbuild.yaml or cloudbuild.json.

  2. In the build config file:

    • Add a serviceAccount field specifying the email address of your service account.
    • If you're storing the build logs in Logging, add a logging field and set the value of the field to CLOUD_LOGGING_ONLY.
    • If you're storing the build logs in a user-created Cloud Storage bucket:
      • Add a logging field and set its value to GCS_ONLY.
      • Add a logsBucket field and set its value to your Cloud Storage bucket location.

    You cannot store logs in the default logs bucket when using the user-specified service account.

    The following build config file configures Cloud Build to execute builds using a user-specified service account and configures build logs to be stored in a user-created Cloud Storage bucket:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    

    Replace the placeholder values in your build config file with the following:

    • LOGS_BUCKET_LOCATION is the Cloud Storage bucket to store build logs. For example, gs://mylogsbucket.
    • PROJECT_NAME is the ID of the Cloud project where you're running the build.
    • SERVICE_ACCOUNT is the email address or unique ID of the service account you want to specify for builds. For example, my-sa-name@my-project-name.iam.gserviceaccount.com.
  3. Start the build using the build config file:

     gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
    

Replace the placeholder values in the above commands with the following:

  • CONFIG_FILE_PATH is path to the build config file.
  • SOURCE_DIRECTORY is path or URL to the source code.

If you don't specify a CONFIG_FILE_PATH and SOURCE_DIRECTORY in the gcloud builds submit command, Cloud Build assumes that the build config file and the source code are in the current working directory.

Running builds using build triggers

  1. In your source repository, create Cloud Build build config file named cloudbuild.yaml or cloudbuild.json.

  2. In the build config file:

    • If you're storing the build logs in Logging, add a logging field and set the value of the field to CLOUD_LOGGING_ONLY.
    • If you're storing the build logs in a user-created Cloud Storage bucket:
      • Add a logging field and set its value to GCS_ONLY.
      • Add a logsBucket field and set its value to your Cloud Storage bucket location.

    You cannot store logs in the default logs bucket when using the user-specified service account.

    The following build config file configures build logs to be stored in a user-created Cloud Storage bucket:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    

    Replace the placeholder value in your build config file with the following:

    • LOGS_BUCKET_LOCATION is the Cloud Storage bucket to store build logs. For example, gs://mylogsbucket.
  3. Specify a service account to use with your build trigger:

    Console

    1. Create or edit your build trigger.
    2. In the Service account field, specify your service account. If you do not specify a service account, the default Cloud Build service account is used.
    3. Click Create to save your build trigger.

    gcloud

    When creating a build trigger, specify your service account using the --service-account flag. If you do not specify a service account, the default Cloud Build service account is used. In the following example, the gcloud command creates a build trigger when the source code is in GitHub:

     gcloud beta builds triggers create github \
        --name=TRIGGER_NAME \
        --repo-name=REPO_NAME \
        --repo-owner=REPO_OWNER \
        --branch-pattern=BRANCH_PATTERN
        --build-config=BUILD_CONFIG_FILE
        --service-account=SERVICE_ACCOUNT
    

    Replace the placeholder values in your build config file with the following:

    • TRIGGER_NAME is the name of your build trigger.
    • REPO_NAME is the name of your repository.
    • REPO_OWNER is the username of the repository owner.
    • BRANCH_PATTERN is the branch name in your repository to invoke the build on.
    • TAG_PATTERN is the tag name in your repository to invoke the build on.
    • BUILD_CONFIG_FILE is the path to your build configuration file.
    • SERVICE_ACCOUNT is the email associated with your service account.

Your build trigger invokes a build in response to the event associated with your trigger. For example, your trigger executes when source code is pushed to the repository. To learn more about triggers, see Creating and managing build triggers.

What's next