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 (Deprecated) and a different service account for building and pushing images to Artifact Registry.
Before you begin
-
Enable the Cloud Build and IAM APIs.
If you plan to use this account to make credentials-related REST API calls, for example to create short-lived credentials, then you also need to enable the IAM Service Account Credentials API.
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.
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 formservice-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com
, whereBUILD_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 Google Cloud project must be in a Google Cloud organization.
- You must start builds in the command line using
gcloud builds submit
orgcloud 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.
- To store your logs in a Cloud Storage bucket, follow the instructions in Storing build logs in the user-created bucket. Make sure that you haven't set a retention policy on the logs bucket as this may prevent Cloud Build from writing build logs to the bucket.
- To store build logs in Logging, grant the
Logs Writer (
roles/logging.logWriter
) role to the service account. See Required IAM permissions to learn more about other necessary service account roles. - For further information on where to store build logs, see Choosing where to store build logs.
Required IAM permissions
To start builds using the user-specified service account, the user requesting the build requires the Service Account User (
roles/iam.serviceAccountUser
) IAM role in the project that has the service account.To store build logs in Logging, grant the Logs Writer (
roles/logging.logWriter
) role to the service account.If you're storing any built images or artifacts in Artifact Registry, Container Registry, or Cloud Storage, grant the necessary access:
- To store images or artifacts in Artifact Registry, grant the
Artifact Registry Create-on-push Writer
(
roles/artifactregistry.createOnPushWriter
) role to the service account. - To store images in Container Registry, grant the Storage Admin (
roles/storage.admin
) role to the service account. - To store artifacts in Cloud Storage, grant the Storage Object Admin (
roles/storage.objectAdmin
) role to the service account.
- To store images or artifacts in Artifact Registry, grant the
Artifact Registry Create-on-push Writer
(
Grant any other additional IAM permissions that the service account requires to run the build. For example, if your build needs to deploy to App Engine, then the service account requires the App Engine Admin role, or if your build specifies source from a Cloud Storage bucket, the service account requires the Storage Admin role.
For instructions on granting IAM roles to a service account, see Configuring access to resources.
Running builds from the command line
In your project root directory, create Cloud Build build config file named
cloudbuild.yaml
orcloudbuild.json
.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 toCLOUD_LOGGING_ONLY
. - If you're storing the build logs in a user-created Cloud Storage bucket:
- Add a
logging
field and set its value toGCS_ONLY
. - Add a
logsBucket
field and set its value to your Cloud Storage bucket location.
- Add a
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 Google 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
.- Add a
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
In your source repository, create Cloud Build build config file named
cloudbuild.yaml
orcloudbuild.json
.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 toCLOUD_LOGGING_ONLY
. - If you're storing the build logs in a user-created Cloud Storage bucket:
- Add a
logging
field and set its value toGCS_ONLY
. - Add a
logsBucket
field and set its value to your Cloud Storage bucket location.
- Add a
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
.
- If you're storing the build logs in Logging, add a
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.- Create or edit your build trigger.
- 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.
- 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, thegcloud
command creates a build trigger when the source code is in GitHub:gcloud 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
- To learn more about the default Cloud Build service accounts, see Cloud Build service account.
- To learn how to grant permissions to the default Cloud Build service account, see Configure access for Cloud Build service account.