Configuring user-specified service accounts

Stay organized with collections Save and categorize content based on your preferences.

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 Google Cloud CLI.

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

Cross-project set up

If the user-specified service account is in a project that is different from the project where you're starting builds, grant the necessary access:

  • In the project that has your user-specified service account, ensure that the iam.disableCrossProjectServiceAccountUsage organization policy constraint is not enforced. This constraint is enforced by default. To disable this organization policy constraint, run the following command where SERVICE_ACCOUNT_PROJECT_ID is the project that contains your user-specified service account:

       gcloud resource-manager org-policies disable-enforce \
          iam.disableCrossProjectServiceAccountUsage \
          --project=SERVICE_ACCOUNT_PROJECT_ID
    
  • In the project that has your user-specified service account, grant the roles/iam.serviceAccountTokenCreator role for the Cloud Build service agent of the project where you're running builds:

       gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
           --member="serviceAccount:BUILD_SERVICE_AGENT \
           --role="roles/iam.serviceAccountTokenCreator"
    

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

    • SERVICE_ACCOUNT_PROJECT_ID: The project ID of the project that contains your user-specified service account.
    • BUILD_SERVICE_AGENT: The email ID of the service agent of the form service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com, where BUILD_PROJECT_NUMBER is the project number of the project where you're running builds. You can get the project number from the project settings page.

Limitations:

  • Your Cloud project must be in a Google Cloud organization.
  • You must start builds in the command line using gcloud builds submit or gcloud beta builds triggers create. To use the Triggers page in the Google Cloud console, the user-specified service account and the build trigger must be in the same project.

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_ID 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, a service account email address looks like: service-account-name@project-id.iam.gserviceaccount.com.

    In this example, the value of the serviceAccount field is: projects/project-id/serviceAccounts/service-account-name@project-id.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

    To run builds using the Trigger UI in the Google Cloud console, the user-specified service account must be in the same project as your build trigger. To use triggers with cross-project service accounts, create the build trigger using the gcloud tool.

    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
        --project=BUILD_PROJECT
    

    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.
    • BUILD_PROJECT is the project where you're starting builds.

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