Migrate to the Cloud SDK-based Gradle plugin

If you are using the Java App Engine SDK-based plugin (com.google.appengine.appengine-gradle) and want to move to the new Google Cloud SDK, you must migrate to the new Google Cloud SDK-based (com.google.cloud.tools.appengine-gradle) plugin.

Benefits of the Cloud SDK-based plugin

Upgrading to the new plugin provides the following benefits:

  • Uses the same authentication credentials as all other Cloud SDK-based commands, which are produced from the standard gcloud auth login flow.

  • Supports the App Engine flexible environment.

  • Updates the local development server automatically as part of the standard Cloud SDK update flow.

  • Supports deploying App Engine service (cron, queues, dos, dispatch) configurations, independently from your service.

  • Sets up environment variables in appengine-web.xml for local service runs.

  • Supports multiple services without requiring EAR packaging.

Notable differences

Before you migrate, be aware of these notable differences:

Cloud SDK dependency
The old plugin runs without any specific local environment dependencies, besides Java, but the new plugin requires that you install the Google Cloud SDK.
No Cloud Endpoints discovery doc generation
The new plugin does not generate Cloud Endpoints discovery docs, a feature available in a separate plugin. Running your Cloud Endpoints backend no longer requires generating this file in a build step as the server now generates it at runtime. You should use the new plugin only if you need to generate client libraries such as for iOS or Android. Learn more about the new plugins by reviewing the Migrating to Endpoints Frameworks for App Engine guide.
EAR file format no longer supported
The new plugin no longer supports the EAR file format for running and deploying multiple services at the same time.
New deployment command
The old plugin calls the appcfg command to deploy applications, while the new plugin deploys using the new gcloud CLI.
JPA/JDO Datanucleus enhancement must be manually configured
If your project uses the gradle-appengine-plugin’s JPA/JDO Datanucleus enhancement, you must manually configure Datanucleus enhancement after switching to the Cloud SDK-based plugin. See an example from Stackoverflow.
Android Studio is not supported
You can switch your Android Studio project to use the new plugin, but the Android Studio App Engine development server and deployment support will not work with this new plugin. To run and deploy your app, you have to invoke Gradle directly.

Migrating to the new plugin

  1. Remove the old gradle-appengine-plugin configuration and imports from your build.gradle file.

  2. Add the new plugin to the classpath of your build.gradle file's buildscript section:

    buildscript {
        repositories {
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.1'
  3. At the root of your service, run the following command to verify that you can run your app locally:

    gradle appengineRun
  4. In your build.gradle file's buildscript section, configure your deployment by specifying your project ID and version:

    appengine {
        deploy {
            version = 'v1'
            project = ‘your GCP project ID"

    The new tooling ignores the application and version elements in your appengine-web.xml file.

  5. At the root of your service, run the following command to verify that you can deploy your application:

    gradle appengineDeploy

Migrating EAR based multi-service configurations

The new plugin does not support EAR packaging. Instead, it supports running multiple services locally without any special packaging steps.

To migrate your EAR-based Gradle project:

  1. Pick a primary service that will be responsible for running the rest of the services. You should select your default service, but it can be any of the services that are run together.

  2. In your appengine configuration, modify the run.services entry to include all the services that should be run by the local development server.

    An example project structure:

      settings.gradle (includes default-service & secondary-service)
           {your-default-service}/build.gradle {includes appengine-gradle-plugin}
           {your-secondary-service}build.gradle {includes appengine-gradle-plugin}

    An example build.gradle buildscript:

    appengine {
        deploy {
            version = '1'
            project = "positive-karma-844"
        run {
            services = [
    // helper method to obtain correct directory and set up dependencies
    def getExplodedAppDir(Project serverProject) {
        // if not 'this' module, then do some setup.
        if (serverProject != project) {
            // make sure we evaluate other modules first so we get the right value
            // make sure we build "run" depends on the other modules exploding wars
            project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar
        return serverProject.tasks.explodeWar.explodedAppDirectory

What's next

  • Now that you have migrated to the new plugin successfully, you can test and deploy your application.

Send feedback about...

App Engine standard environment for Java