Set build environment variables (source deploy)

Build environment variables are key-value pairs that let you pass configurationinformation tobuildpacks when deployingfrom source code. For example, at build time, you might want to customizecompiler options, specify build-time certificates, configure parameters, and soforth.

This page shows how to set build environment variables that are available atbuild time, and is relevant for platform developers who are deployingCloud Runservices orfunctions from source. The build environmentvariable gcloud CLI flags are supported forsource deployments (--source), and notsupported forcontainer image deployments (--image).

You can use environment variables for service or function configuration, but we don'trecommend them as a way to store secrets such as database credentials or API keys.Store sensitive values outside both your source code and environment variables. Tostore secrets, we recommend using Secret Manager.To configure services that access secrets stored in Secret Manager,seeConfigure secrets.

Before you begin

  • Enable the Cloud Run Admin API and Cloud Build APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

    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 theCloud 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:

Click to view required roles for the Cloud Build service account

Cloud Build automatically uses theCompute 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 grantCloud Run Builder (roles/run.builder) to the Compute Engine default service account on your project:

gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com\--role=roles/run.builder

ReplacePROJECT_NUMBER with your Google Cloud project number, andPROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, seeCreating and managing projects.

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

Note:

Theiam.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 thengrant 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, usePolicy Simulator to see the impact of the change, and thengrant and revoke the appropriate roles.

For a list of IAM roles and permissions that are associated withCloud Run, seeCloud Run IAM rolesandCloud Run IAM permissions.If your Cloud Run service interfaces withGoogle Cloud APIs, such as Cloud Client Libraries, see theservice identity configuration guide.For more information about granting roles, seedeployment permissionsandmanage access.

Maximum number of build environment variables and limits

You can define up to 100 build environmentvariables, with a total key and value limit of 64 KiB.

Set build environment variables

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

Note: Keys must start with an uppercase ASCII letter, and consist of uppercaseASCII letters, digits, and underscores. You should avoid creating variable keyswith aGOOGLE_* prefix.View all supported buildpacks environment variables.

gcloud

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

gcloudrundeploySERVICE\--source.\--set-build-env-varsKEY1=VALUE1,KEY2=VALUE2

Replace:

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

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

Update build environment variables

You can update build environment variables for existing services. This is anon-destructive approach that changes or adds build environment variables, butdoes not delete the build environment variables.

gcloud

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

gcloudrundeploySERVICE\--source.\--update-build-env-varsKEY1=VALUE1,KEY2=VALUE2

If you are deploying a function, add the--function flag with the functionentry 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:

gcloudrundeploySERVICE\--source.\--remove-build-env-varsKEY1=VALUE1,KEY2=VALUE2

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

gcloudrundeploySERVICE\--source.\--clear-build-env-varsKEY1=VALUE1,KEY2=VALUE2

If you are deploying a function, add the--function flag with the functionentry 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:

gcloudrundeploySERVICE\--source.\--build-env-vars-fileFILE_NAME.yaml

ReplaceFILE_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 functionentry point from your source code.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.