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 such as the ability to update builds or write logs.

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.

Limitations

  • User-specified service accounts only work with manual builds; they don't work with build triggers.
  • You must create the user-specified service account in the same Cloud project where you're running builds.

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.

Setting up build logs

To specify your own service account for builds, you must configure storing your build logs either in Cloud Logging or in your own Cloud Storage bucket:

Required IAM permissions

For instructions on granting IAM roles to a service account, see Configuring access for project members.

Running builds

  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 your Cloud Storage bucket, add a logsBucket field pointing to your Cloud Storage bucket.

    YAML 

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

    JSON 

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

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

    • LOGS_BUCKET_LOCATION: the Cloud Storage bucket to store build logs. For example, gs://mylogsbucket.
    • PROJECT_NAME: the Cloud project name where you're running the build.
    • SERVICE_ACCOUNT: email address or unique ID of the service account you want to specify for builds.

  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: path to the build config file.
  • SOURCE_DIRECTORY: 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.

What's next