Test and deploy your application

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

OK

Go Java Node.js PHP Python Ruby

Learn how to run your application locally, deploy it, and test on App Engine.

Run locally

To test your application before deploying, run your application in your local environment with the development tools that you usually use.

Before deploying your application

Before deploying your application:

• The Owner of the Google Cloud project must set up your Google Cloud project for App Engine.
• Ensure that your user account includes the required privileges.

Deploy your application

You can use any of the following techniques to deploy your app:

• Use the Google Cloud CLI to deploy your app's source code and a Maven POM or Gradle build file. Cloud Build will build your app and deploy it to App Engine.

• Use the App Engine plugin for Maven or Gradle, which builds your app locally and deploys the built app to App Engine.

• Use any build framework to build a JAR (executable JAR) locally, then use the Google Cloud CLI to deploy the JAR to App Engine.

To programmatically deploy your apps, use the Admin API.

Deploy your app's source code

If you use Maven or Gradle to manage your app's local builds, and if all of your app's dependencies are publicly available for download, you can enter the gcloud app deploy command from the directory that contains your app's pom.xml or build.gradle file:

gcloud app deploy

The command instructs Cloud Build to use Google Cloud's buildpacks to build your app and deploy it to App Engine.

If you use Maven:

• The buildpack uses the following build command: mvn clean package --batch-mode -DskipTests

• If your app's root directory contains a mvnw file, the build command substitutes ./mvnw in place of mvn. Cloud Build then looks in the target directory for the jar file with a Main-Class manifest entry and creates an entrypoint with the value java -jar <jarfile>.

If you use Gradle:

• The buildpack uses the following build command: gradle clean assemble -x test --build-cache

• If your app's root directory contains a gradlew file the build command substitutes ./gradlew in place of gradle. Cloud Build then looks in the build/libs directory for the jar file with a Main-Class manifest entry and creates an entrypoint with the value java -jar <jarfile>.

• Make sure there is no pom.xml in the root of your project. Maven projects take precedence over Gradle projects.

Use the App Engine Maven or Gradle plugin

App Engine provides Maven and Gradle plugins that you can use to build and deploy your app. For example, after you set up the App Engine Maven plugin, you can enter the following command from the directory that contains your project's pom.xml file:

mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

Replace PROJECT_ID with the ID of your Google Cloud project. If your pom.xml file already specifies your project ID , you don't need to include the -Dapp.deploy.projectId property in the command you run.

For more information, see Using Apache Maven and the App Engine plugin or Using Gradle and the App Engine plugin.

Deploy an executable JAR

Use any build framework to build an executable JAR locally, and use either of the following methods to deploy an executable JAR.

• If you created an app.yaml file:

  1. Copy the file into the same directory as the executable JAR file you created.

  2. From the directory that contains the app.yaml and your JAR, enter the following command:

     gcloud app deploy

• If you haven't created an app.yaml file, enter the following command:

  gcloud app deploy your-executable.jar

  gcloud app deploy will create an app.yaml file that contains the minimum settings, using all default values.

View build logs

Cloud Build streams build and deploy logs that are viewable in the Cloud Build Build history section of the Google Cloud console. To view builds in the app's region, use the Region menu to filter by the region.

Note the following about this deployment technique:

• If your app has dependencies that are only available locally, Cloud Build is not able to build your app and your deployment will fail. In this case, we recommend using the App Engine Maven or Gradle plugin instead.

• Building your app uses Cloud Build quota and storing your app's source code uses Cloud Storage quota. Cloud Build and Cloud Storage provide free quotas, so you won't incur costs from deploying App Engine apps until you surpass the free quotas. For information, see Pricing.

• It isn't possible to specify additional arguments for the Gradle build command. For more information, see the Issue tracker.

Manage build images

Caution: Container Registry is deprecated. Effective March 18, 2025, Container Registry is shut down, and writing images to Container Registry is unavailable. For details on the deprecation and how to migrate to Artifact Registry, see Container Registry deprecation.

Each time you deploy a new version:

1. App Engine creates a container image using the Cloud Build service.

2. Cloud Build builds the container image in the app's region, and runs in the App Engine standard environment.

3. App Engine stores built container images in Artifact Registry. You can download these images to keep or run elsewhere.

After deployment is complete, App Engine no longer needs the container images. The container images aren't automatically deleted. To avoid reaching your storage quota, you can safely delete any images you don't need. However, if you might need the images in the future or want to keep a copy of the images, you need to export a copy prior to deletion. For more information about managing images in Artifact Registry, see Manage images.

Ignore files

You can use a .gcloudignore file to specify files and directories that won't be uploaded to App Engine when you deploy your services. This is useful for ignoring build artifacts and other files that don't need to be uploaded with your deployment.

Note: You cannot specify the skip_files field in your app.yaml file if you have a .gcloudignore file.

View your application

After you deploy your application to App Engine, you can run the following command to launch your browser and view it at https://PROJECT_ID.REGION_ID.r.appspot.com:

gcloud app browse

Test on App Engine before shifting traffic

Before configuring a new version to receive traffic, you can test it on App Engine. For example, to test a new version of your default service:

1. Deploy your new version, but prevent traffic from being automatically routed to the new version:

   mvn appengine:deploy -Dapp.deploy.projectId=PROJECT_ID -Dapp.deploy.promote=False

2. Access your new version by navigating to the following URL:

   https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

   Note: You can find the version ID in the Google Cloud console or specify one when you deploy with the --version flag. The Google Cloud CLI also outputs the version ID when you deploy.

   Now you can test your new version in the App Engine runtime environment. You can debug your application by viewing its logs. For more information, see Writing Application Logs.

   App Engine routes requests sent to https://PROJECT_ID.REGION_ID.r.appspot.com to the version previously configured to receive traffic.

3. When you want to send traffic to the new version, use the Google Cloud console to migrate traffic:

   Manage versions

   Select the version you just deployed and click Migrate traffic.

You can use the same process to test new versions of other services by replacing default in the URL with your service's name:

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

For more information about targeting specific services and versions, see How requests are routed.

Use build environment variables

You can set build environment variables for runtimes that support buildpacks.

Build environment variables are key-value pairs that you can specify to configure the buildpack you use to deploy your app. For example, you might want to specify compiler options.

Before you begin:

• Keys must start with an uppercase ASCII letter, and can include uppercase ASCII letters, digits, and underscores.
• You should avoid creating any variables with a GOOGLE_* key prefix.
• The following keys are reserved for Google's use:
  • GOOGLE_RUNTIME
  • GOOGLE_RUNTIME_VERSION
  • GOOGLE_ENTRYPOINT
  • GOOGLE_DEVMODE
• You can use any key that is supported by buildpacks.

To use environment variables with buildpacks, specify the build_env_variables field in your app.yaml file.

Learn more about buildpacks.

Use Cloud Profiler

Cloud Profiler is a statistical, low-overhead profiler that continuously gathers CPU usage and memory-allocation information from your production applications. It attributes that information to your app's source code, helping you identify the parts of the app consuming the most resources, and otherwise illuminating the performance characteristics of the code.

To use Cloud Profiler, set up your app's configuration files as described in Starting your program and redeploy the app.

Use the local development server

See the instructions about how to use the local development server for Java.

Use Cloud Trace

Cloud Trace is useful for understanding how requests propagate through your application. You can inspect detailed latency information for a single request or view aggregate latency for your entire application.

To view trace details in Cloud Trace, you can follow Find and explore traces. In the Trace explorer, you can use the filters to filter by your specific App Engine service and version.