Google App Engine

Git and Push-to-Deploy

Push-to-Deploy is feature of App Engine that allows you to deploy an application by pushing its source files from a Git repository to a remote repository hosted on the Google Cloud Platform. The Cloud repository is a fully-functional Git repository that supports standard Git operations like push, pull, clone and log. You can use Push-to-Deploy to deploy directly from a Git repository on your local workstation or via a connected repository hosted on GitHub. When you push your code, Push-to-Deploy automatically uploads and launches the application. Push-to-Deploy works for applications written in Python, PHP and Java.

Read the Java requirements section of this page before you use Push-to-Deploy to deploy a Java application. Push-to-Deploy for Java requires you to enable billing for your Cloud project.

Push-to-Deploy is an optional feature of App Engine. If you are using the native SDK methods for App Engine deployment, you can continue to do so. Note, however, that only Push-to-Deploy pushes source files to your Cloud repository.

Installing Git

Download and install Git on your local system.

Creating a Cloud Project

If you don't already have a Cloud project, you must create one now. When you create the project, note its project ID, as you will use it in subsequent steps.

To create a new Cloud project:

  1. Open the Cloud Developer Console.

  2. Click Create Project.

  3. Enter a project name and a project ID or accept the defaults.

  4. Click Create.

Setting up the Cloud repository

Once you have a Cloud project, the next step is to set up the Cloud repository. You can choose to do one of the following:

  • Create a new Cloud repository (for deploying directly from a local Git repository)
  • Create a new Cloud repository and connect it to an existing repository on GitHub

Creating a new Cloud repository

To create a new Cloud repository where you are deploying directly from a Git repository on your local workstation:

  1. Open your project in the Cloud Developer Console.

  2. Select Cloud Development > Releases in the left-hand navigation panel.

  3. Click Create a New Repo.

    Note the repository URL that is displayed. You may use this URL later to perform Git operations on the Cloud repository.

Creating a new Cloud repository and connecting it to GitHub

To create a new Cloud repository and connect it to an existing repository on GitHub:

  1. Open your project in the Cloud Developer Console.

  2. Select Cloud Development > Releases in the left-hand navigation panel.

  3. Click Connect a GitHub Repo.

  4. Enter the GitHub repository URL in the dialog box that appears. The repository URL is in the format https://github.com/username/repository. This is the same URL that you open in your web browser when you are viewing the repository on the GitHub site.

  5. Read and consider the authentication request that is displayed in the dialog box. Select the Consent option if you consent to the request.

  6. Click Connect.

  7. Authorize access to your repository in the page on GitHub.com when prompted.

    Note the repository URL that is displayed. You may use this URL later to perform Git operations on the Cloud repository.

Selecting a release type

After you have set up your Cloud repository, you must select a release type for your application.

Release types vary by language. For Python and PHP, Push-to-Deploy deploys your source directly to App Engine. For Java applications, Push-to-Deploy builds your application using Maven and runs unit tests before deployment. If you are deploying a Java application and you have not already enabled billing for your Cloud project, you will be prompted to do so when you choose the Java release type. See Billing.

To select a release type:

  1. Select Cloud Development > Releases in the left-hand navigation panel of the Developer Console.

  2. Select one of the following from the Release Type list.

    • Deploy Source. Use this option for Python and PHP applications.
    • Java: Maven Build, Unit Test and Deploy. This option builds your Java application, runs unit tests and deploys the WAR file produced by the build if there are no test failures or errors.

Setting up the local environment

If you are pushing your application source code directly from a local repository to your Cloud repository, you must perform some setup steps to prepare your local environment for Push-to-Deploy. If you are using a connected GitHub repository, skip this step and instead manually create a Git repository on your local system and configure it to work with your repository on GitHub.

You use the gcloud utilities provided by the Google Cloud SDK to set up the local environment for Push-to-Deploy. This includes setting up authentication, creating a new local Git repository and adding the Cloud repository as a Git remote.

To set up the local environment:

  1. Download and install the Google Cloud SDK on your local system.

  2. At a command prompt, navigate to the directory where you want your project directory to be located. Your project directory will have the same name as your project ID and will contain a directory named default for your local Git repository.

  3. Run gcloud auth login at the prompt. This command acquires credentials for your Cloud repository and configures the local instance of Git to use them.

    $ gcloud auth login
    

    The gcloud auth login command prints an authentication URL to the terminal. If you are running the command on a local system, this URL opens automatically in a browser on your desktop. If you are running the command on a remote system (for example, using ssh), you must manually paste the URL into a browser window and then manually paste the acquired token back into the terminal.

  4. Read and consider the permissions request that appears in the browser window. Click Accept to accept the request.

  5. If prompted at the command line, enter your Cloud project ID.

  6. Run gcloud init. This command creates the local Git repository and adds the Cloud repository as the Git origin remote.

    $ gcloud init PROJECT
    

    where PROJECT is the project ID of your Cloud project.

    gcloud init creates a directory named PROJECT/default in the current directory. This directory holds your local Git repository.

You can now use the local repository as part of your development workflow.

Deploying the application

When you are ready to deploy the application to App Engine, commit your changes and run the git push command:

git push origin master

Viewing release history and build status

You can view the release history and current deployment status for your application in the Developer Console.

To view the status and history:

  1. Select Cloud Development > Releases in the left-hand navigation panel of the Developer Console.

  2. Click Release History in the page that opens. A list of application deployments appears. The last deployment task completed appears in the Tasks column.

  3. Click in the Tasks column to see a list of tasks completed for the deployment.

Viewing build logs and WAR files in Cloud Storage

When Push-to-Deploy builds a Java application, it generates an archive named upload.war that contains the application source. The WAR file and saved build logs are stored in Cloud Storage.

To view build logs and WAR files:

  1. Click Cloud Storage in the left-hand navigation panel of the Cloud Console.

  2. Click the bucket whose name begins with p2d_ to display a list of folders. To see the build logs and WAR file for a specific commit ID, click on the folder whose name matches the ID.

Java requirements

Push-to-Deploy for Java uses Maven and Jenkins to build, test and deploy Java applications. It uses Maven to build the application and JUnit with the Maven Surefire plugin to run unit tests. If no errors or test failures occur, the application is deployed to App Engine for serving.

Push-to-Deploy for Java has the following additional requirements, including setting up billing for your account.

Maven

Note the following for Maven build and test:

  • Only Maven version 3.1.0 is supported.
  • pom.xml must be in the root folder of the source repository.
  • Push-to-Deploy builds the Java application with the following command: mvn clean package -Dmaven.test.skip=true.
  • Unit tests are run by executing the Maven goal test in the root directory.
  • Unit tests must generate XML test reports in the target/surefire-reports directory.
  • The single WAR file in the target directory is deployed to App Engine if there are no test failures or errors.

Java

The Java compiler plugin for Maven version 3.1 defaults to version 1.5 for the source and target. If you need a later Java version, you must explicitly specify it in your pom.xml file. The following code shows how to specify Java version 1.7:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <version>2.5.1</version>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>1.7</source>
        <target>1.7</target>
    </configuration>
</plugin>

Jenkins, GCE and GCS

Every time you push code changes to the Google Cloud repository, Push-to-Deploy provisions a n1-standard-1 Google Compute Engine (GCE) VM. This VM hosts the Jenkins master used to build your project. In addition, the build logs and WAR file produced by your build are uploaded to a Google Cloud Storage (GCS) bucket owned by your project. The GCE VM is shut down after your build has exited -- in other words, has completed successfully or failed.

Billing

You must set up billing for your account before you can deploy a Java application. If you have not already enabled billing, you will be prompted to do so when you set up your deployment.

Note the following:

  • You will be charged for the GCE VM time used by your build and GCS storage consumed by your build logs and WAR file.
  • You should expect to pay at least 1 cent per build for GCE VM, and more if your build takes more than 10 minutes to complete. Please see GCE VM pricing for details.
  • The cost of GCS storage depends on the size of logs and WAR file produced by your build. Please see GCS pricing for details. You can reduce costs by deleting the logs and/or WAR files that are no longer needed. By default, logs and WAR files are deleted after 14 days

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.