Set build environment variables (source deploy)

Build environment variables are key-value pairs that let you pass configuration information to buildpacks when deploying from source code. For example, at build time, you might want to customize compiler options, specify build-time certificates, configure parameters, and so forth.

This page shows how to set build environment variables that are available at build time, and is relevant for platform developers who are deploying Cloud Run services or functions from source. The build environment variable gcloud CLI flags are supported for source deployments (--source), and not supported for container image deployments (--image).

Before you begin

Enable the Cloud Run Admin API and the Cloud Build API:
```
gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com
```
After the Cloud Run Admin API is enabled, the Compute Engine default service account is automatically created.

Required roles

You or your administrator must grant the deployer account and the Cloud Build service account the following IAM roles.

Click to view required roles for the deployer account

To get the permissions that you need to build and deploy from source, ask your administrator to grant you the following IAM roles:

Cloud Run Source Developer (roles/run.sourceDeveloper) on your project
Service Account User (roles/iam.serviceAccountUser) on the Cloud Run service identity

Click to view required roles for the Cloud Build service account

Cloud Build automatically uses the Compute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior. For Cloud Build to build your sources, ask your administrator to grant Cloud Run Builder (roles/run.builder) to the Compute Engine default service account on your project:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

Replace PROJECT_NUMBER with your Google Cloud project number, and PROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, see Creating and managing projects.

Granting the Cloud Run builder role to the Compute Engine default service account takes a couple of minutes to propagate.

Note:

The iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint prevents the Editor role from being automatically granted to default service accounts. If you created your organization after May 3, 2024, this constraint is enforced by default.

We strongly recommend that you enforce this constraint to disable the automatic role grant. If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and then grant these roles yourself.

If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, use Policy Simulator to see the impact of the change, and then grant and revoke the appropriate roles.

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run service interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Set build environment variables

You can set build environment variables to establish new variables or completely replace existing build variables.

gcloud

To set build environment variables when deploying a service from source code, use the --set-build-env-vars flag:

gcloud beta run deploy SERVICE \
    --source . \
    --set-build-env-vars KEY1=VALUE1,KEY2=VALUE2

Replace:

SERVICE with name of your Cloud Run service.
KEY1=VALUE1,KEY2=VALUE2 with the comma-separated list of variable names and their values that are deployed alongside a function that let you pass configuration information to buildpacks.

If you are deploying a function, add the --function flag with the function entry point from your source code.

Update build environment variables

You can update build environment variables for existing services. This is a non-destructive approach that changes or adds build environment variables, but does not delete the build environment variables.

gcloud

To update build environment variables for existing services, use the --update-build-env-vars flag:

gcloud beta run deploy SERVICE \
    --source . \
    --update-build-env-vars KEY1=VALUE1,KEY2=VALUE2

If you are deploying a function, add the --function flag with the function entry point from your source code.

Delete build environment variables

You can delete build environment variables for existing services.

gcloud

To remove build environment variables for existing services, use the --remove-build-env-vars flag:

gcloud beta run deploy SERVICE \
    --source . \
    --remove-build-env-vars KEY1=VALUE1,KEY2=VALUE2

Alternatively, you can clear build environment variables by using the --clear-build-env-vars for existing services:

gcloud beta run deploy SERVICE \
    --source . \
    --clear-build-env-vars KEY1=VALUE1,KEY2=VALUE2

If you are deploying a function, add the --function flag with the function entry point from your source code.

Use a build environment variables file

You can use a build environment variables file for existing functions.

gcloud

To set build environment variables from a file, use the --build-env-vars-file flag:

gcloud beta run deploy SERVICE \
    --source . \
    --build-env-vars-file FILE_NAME.yaml

Replace FILE_NAME.yaml where the contents of the file, which should look as follows:

 KEY1: VALUE1
 KEY2: VALUE2

If you are deploying a function, add the --function flag with the function entry point from your source code.