Para definir variáveis de ambiente para builds remotos, use o descritor de projeto project.toml.
O descritor de projeto project.toml é usado pelo Cloud Build quando a imagem de contêiner é criada.
Antes de começar
Sign in to your Google Cloud account. If you're new to
Google Cloud,
create an account to evaluate how our products perform in
real-world scenarios. New customers also get $300 in free credits to
run, test, and deploy workloads.
In the Google Cloud console, on the project selector page,
select or create a Google Cloud project.
No diretório raiz do serviço, crie ou atualize o descritor de projeto project.toml para incluir a seção [[build.env]] e qualquer uma das variáveis de ambiente compatíveis:
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[[["\u003cp\u003eYou can set environment variables during the build process of your container image for both local and remote builds.\u003c/p\u003e\n"],["\u003cp\u003eLocal builds require the installation of Docker CE and the Pack CLI, and utilize the \u003ccode\u003e--env\u003c/code\u003e flag in the \u003ccode\u003epack build\u003c/code\u003e command to set environment variables.\u003c/p\u003e\n"],["\u003cp\u003eRemote builds use the \u003ccode\u003eproject.toml\u003c/code\u003e file to define environment variables within the \u003ccode\u003e[[build.env]]\u003c/code\u003e section, which are then applied during the build on Cloud Build.\u003c/p\u003e\n"],["\u003cp\u003eTo perform a remote build, you need to create a Docker repository in Artifact Registry, use gcloud to submit your application and verify the upload success.\u003c/p\u003e\n"],["\u003cp\u003eThe content also provides links to required tools and example commands to build different sample applications, to make the process smoother for developers.\u003c/p\u003e\n"]]],[],null,["# Set environment variables to configure builds\n\nYou can configure environment variables that are set during the build of your\ncontainer image.\n\nYou can also customize your container image by\n[extending the build and run images](/docs/buildpacks/build-run-image).\n\nLocal builds\n------------\n\nFor local builds, you must have the Pack CLI and Docker installed.\n\n### Before you begin\n\n1. Install [Docker Community Edition (CE)](https://docs.docker.com/engine/installation/) on your workstation. Docker is used by `pack` as an OCI image builder.\n2. Install [Pack CLI](https://buildpacks.io/docs/tools/pack/).\n3. Install the [Git source control](https://git-scm.com/downloads) tool to fetch the sample application from GitHub.\n\n### Set environment variables\n\nTo set environment variables for local builds, you append the `--env` flag to\nthe `pack` command for each environment variable.\n\nYou can use one or more of the\n[environment variables that are supported by your runtime](/docs/buildpacks/service-specific-configs). \n\n pack build \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e \\\n --env \u003cvar translate=\"no\"\u003eENVIRONMENT_VARIABLE\u003c/var\u003e\n\nReplace:\n\n- `SERVICE_NAME` with the name of the service for your application or function.\n- `ENVIRONMENT_VARIABLE` with the environment variable that you want to set during build time.\n\nExample\n\n: To set the `GOOGLE_ENTRYPOINT=\"gunicorn -p :8080 main:app\"` environment variable\n in your container image, you run the following command:\n\n pack build my-app \\\n --builder gcr.io/buildpacks/builder:v1 \\\n --env GOOGLE_ENTRYPOINT=\"gunicorn -p :8080 main:app\"\n --env MY-LOCAL-ENV-VARIABLE\n\nRemote builds\n-------------\n\nTo set environment variables for remote builds, you use the\n[`project.toml` project descriptor](https://buildpacks.io/docs/app-developer-guide/using-project-descriptor/).\nThe `project.toml` project descriptor is used by Cloud Build when your\ncontainer image is built.\n\n### Before you begin\n\n- Sign in to your Google Cloud account. If you're new to Google Cloud, [create an account](https://console.cloud.google.com/freetrial) to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.\n- In the Google Cloud console, on the project selector page,\n select or create a Google Cloud project.\n\n | **Note**: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.\n\n [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n-\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n-\n\n\n Enable the Cloud Build and Artifact Registry APIs.\n\n\n [Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=cloudbuild.googleapis.com, artifactregistry.googleapis.com&redirect=https://cloud.google.com/docs/buildpacks/build-application)\n-\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n- If you're using an external identity provider (IdP), you must first\n [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n\n-\n To [initialize](/sdk/docs/initializing) the gcloud CLI, run the following command:\n\n ```bash\n gcloud init\n ```\n\n- In the Google Cloud console, on the project selector page,\n select or create a Google Cloud project.\n\n | **Note**: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.\n\n [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n-\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n-\n\n\n Enable the Cloud Build and Artifact Registry APIs.\n\n\n [Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=cloudbuild.googleapis.com, artifactregistry.googleapis.com&redirect=https://cloud.google.com/docs/buildpacks/build-application)\n-\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n- If you're using an external identity provider (IdP), you must first\n [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n\n-\n To [initialize](/sdk/docs/initializing) the gcloud CLI, run the following command:\n\n ```bash\n gcloud init\n ```\n\n| If you've already installed Google Cloud CLI previously, make sure you have the\n| latest available version by running `gcloud components update`.\n1. Ensure that your Google Cloud project has access to a container image repository. To configure access to a\n [Docker repository in\n Artifact Registry](/artifact-registry/docs/docker/store-docker-container-images):\n\n 1. Create a new Docker repository in the same location of your Google Cloud project. \n\n ```bash\n gcloud artifacts repositories create REPO_NAME \\\n --repository-format=docker \\\n --location=REGION --description=\"\u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e\"\n ```\n Replace:\n - `REPO_NAME` with the name that you choose for your Docker repository.\n - `REGION` with the [location](/artifact-registry/docs/repositories/repo-locations) in or nearest to the location of your Google Cloud project.\n - `DESCRIPTION` with a description of your choice.\n\n For example, to create a `docker` repository in\n `us-west2` with the description \"Docker repository\", you run: \n\n ```bash\n gcloud artifacts repositories create buildpacks-docker-repo --repository-format=docker \\\n --location=us-west2 --description=\"Docker repository\"\n ```\n 2. Verify that your repository was created: \n\n ```bash\n gcloud artifacts repositories list\n ```\n\n You should see name that you choose for your Docker repository in the list.\n\n### Optional: Download a sample application\n\n1. Clone the sample repository to your local machine: \n\n ```bash\n git clone https://github.com/GoogleCloudPlatform/buildpack-samples.git\n ```\n2. Change to the directory that contains the application sample code:\n\n ### Go\n\n ```sh\n cd buildpack-samples/sample-go\n ```\n\n ### Java\n\n ```sh\n cd buildpack-samples/sample-java-gradle\n ```\n\n ### Node.js\n\n ```sh\n cd buildpack-samples/sample-node\n ```\n\n ### PHP\n\n ```sh\n cd buildpack-samples/sample-php\n ```\n\n ### Python\n\n ```sh\n cd buildpack-samples/sample-python\n ```\n\n ### Ruby\n\n ```sh\n cd buildpack-samples/sample-ruby\n ```\n\n ### .NET\n\n ```sh\n cd buildpack-samples/sample-dotnet\n ```\n\n### Build the application with environment variables\n\n1. In the root directory of your service, create or update your `project.toml` project descriptor to include the `[[build.env]]` section and any of the [supported\n environment variable](/docs/buildpacks/service-specific-configs): \n\n ```bash\n [[build.env]]\n name = \"\u003cvar translate=\"no\"\u003eENVIRONMENT_VARIABLE_NAME\u003c/var\u003e\"\n value = \"\u003cvar translate=\"no\"\u003eENVIRONMENT_VARIABLE_VALUE\u003c/var\u003e\"\n ```\n\n Replace:\n - `ENVIRONMENT_VARIABLE_NAME` with the name of a [supported\n environment variable](/docs/buildpacks/service-specific-configs).\n - `ENVIRONMENT_VARIABLE_VALUE` with the corresponding value for the specified environment variable.\n\n **Example** \n\n ```bash\n [[build.env]]\n name = \"GOOGLE_ENTRYPOINT\"\n value = \"gunicorn -p :8080 main:app\"\n ```\n2. Use `gcloud` to submit the application source code to Cloud Build: \n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME\n ```\n\n Replace:\n - `LOCATION` with the region name of your container repository. Example: **us-west2**`-docker.pkg.dev`\n - `PROJECT_ID` with the ID of your Google Cloud project.\n - `REPO_NAME` with the name of your Docker repository.\n - `IMAGE_NAME` with the name of your container image.\n\n \u003cbr /\u003e\n\n **Examples**: If you downloaded a sample application, you run the\n corresponding command:\n\n ### Go\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-go\n ```\n\n ### Java\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-java-gradle\n ```\n\n ### Node.js\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-node\n ```\n\n ### PHP\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-php\n ```\n\n ### Python\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-python\n ```\n\n ### Ruby\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-ruby\n ```\n\n ### .NET\n\n ```sh\n gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-dotnet\n ```\n3. Verify that the sample application was successfully published to \u003cvar translate=\"no\"\u003eREPO_NAME\u003c/var\u003e: \n\n ```bash\n gcloud artifacts docker images list LOCATION-docker.pkg.dev/project-id/REPO_NAME\n ```\n\n Replace:\n - `LOCATION` with the region name of your container repository. Example: **us-west2**`-docker.pkg.dev`\n - `PROJECT_ID` with the ID of your Google Cloud project.\n - `REPO_NAME` with the name of your Docker repository."]]