Running builds with GitHub Checks

Cloud Build provides a Cloud Build GitHub App, which uses GitHub Checks events to automatically build your code each time you create a new branch or push code to GitHub.

This tutorial explains how you can install and configure the app, and automatically trigger builds on GitHub.

Objectives

In this tutorial, you will:

  • Prepare a GitHub repo with some source code to build.
  • Install and configure the Google Cloud Build GitHub app.
  • Make changes to your source code on GitHub and create a pull request for the changes.
  • Observe that the Google Cloud Build app builds your code on creating a pull request.
  • View the build results on GitHub and the GCP Console.
  • Learn about the different ways to configure your builds.

Costs

This tutorial uses the following billable components of GCP:

  • Cloud Build

    First 120 build-minutes per day are free; you will be charged for builds consumed above this threshold. For more information see the Pricing page.

  • Container Registry

    If you're building using a Dockerfile and storing the built image in Container Registry, you will be charged for storage and the network egress used by your Docker images. For information see the Container Registry Pricing page.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your Google Cloud Platform project.

    Learn how to enable billing

  4. Create a GitHub account if you don't have one already.

Preparing a GitHub repository with source files

To use the Google Cloud Build app, your repository must contain either a Dockerfile or a cloudbuild.yaml file to configure your build.

The Dockerfile is the config file for building Docker containers. If you're using the app for Docker builds, it is sufficient if your repo contains a Dockerfile. The example in this tutorial is configured with a Dockerfile.

cloudbuild.yaml is the config file for Cloud Build. Use a cloudbuild.yaml in the following scenarios:

  • If you wish to fine-tune your Docker builds, you can provide a cloudbuild.yaml in addition to the Dockerfile. If your repository contains a Dockerfile and a cloudbuild.yaml, the Google Cloud Build app will use the cloudbuild.yaml to configure the builds.

  • If you wish to use the Google Cloud Build app for non-Docker builds.

For instructions on creating a cloudbuild.yaml, read Build Configuration Overview and Creating a Basic Build Config File.

To work through the example in this tutorial, you'll need a sample GitHub repository with some source code to build. Use the following steps to fork a repository that contains the source files used in this tutorial. The source files in the repo includes a helloworld.sh file and Dockerfile, which you will use to build a Docker image.

  1. On GitHub, navigate to /GoogleCloudBuild/gcbapp-dockerfile-example.

  2. On the top-right corner of the page, click Fork.

    Screenshot of the fork button

    Now you have a copy of the gcbapp-dockerfile-example repo with source files.

Installing the Google Cloud Build app

In this section you'll install the Google Cloud Build app. This will allow you to connect your GitHub repository with your GCP project and set up continuous integration for gcbapp-dockerfile-example.

During the installation and set up process you will first be asked to authorize the Google Cloud Build app to connect to Google Cloud Platform. After authorizing, you are redirected to GCP Console where you'll select your GCP project. You'll then be redirected back to GitHub.

The steps below provide instructions for installing the app only for the gcbapp-dockerfile-example repo; but you can choose to install the app for more or all your repositories.

  1. Go to the GitHub marketplace page for the Google Cloud Build app.

    Open Cloud Build app page

  2. Click Setup with Google Cloud Build.

  3. Sign in to GitHub.

  4. In the Edit your plan page, select or update your billing information and click grant this app access.

  5. Select one of the following options based on your business need:

    • Only select repositories and enter gcbapp-dockerfile-example to only connect the example docker repository.

    • All repositories if you want to connect all of your repositories.

  6. Click Install.

  7. Sign in to GCP.

    The Authorization page is displayed where you are asked to authorize the Google Cloud Build app to connect to Google Cloud Platform.

    Screenshot of the authorize button

  8. Click Authorize Google Cloud Build by GoogleCloudBuild.

    You are redirected to the GCP Console.

  9. Select your GCP project.

  10. Check the consent checkbox and click Next.

  11. In the Repository selection page that appears, select the repositories you want to connect to your GCP project and click Connect.

  12. Click Done.

You have successfully installed the Google Cloud Build and connected your chosen repositories to your GCP project.

Connecting additional repositories

If you want to connect additional repositories to your GCP project after you have installed the Google Cloud Build app using the steps in the previous section, follow the steps below:

  1. If you have not already done so, obtain the installation ID of your Google Cloud Build app instance:

    a. Navigate to https://github.com/settings/installations.

    b. Locate the Google Cloud Build app and click Configure next to it.

    c. In your browser's address bar, examine the URL of the Configure page. The installation ID is at the end of the URL as follows:

    https://github.com/settings/installations/[INSTALLATION_ID]

  2. Access the following URL, substituting the app installation ID from step 1:

    https://console.cloud.google.com/m/gcb/github/setup?installation_id=[INSTALLATION_ID]

  3. In the Connect Repositories page that appears, locate the desired GCP project and click Edit next to it.

  4. In the page that appears, select the repositories you want to connect and click Connect.

  5. Click Done.

Build using the Google Cloud Build app

The source files in gcbapp-dockerfile-example consist of a simple helloworld.sh file and a Dockerfile. In this section, you'll make changes to the code in helloworld.sh and create a pull request to check in your changes.

The Google Cloud Build app builds your code when you create or modify a branch. Since starting a pull request leads to creating a new branch or modifying an existing branch, your code is built each time you start a new pull request.

  1. Open helloworld.sh in gcbapp-dockerfile-example:

    https://github.com/[GITHUB_USERNAME]/gcbapp-dockerfile-example/blob/master/helloworld.sh
    
  2. Click on the pencil icon to edit the file.

    Screenshot of the edit file button

  3. Add the following line at the end of the file:

    echo "The time is $(date)."
    
  4. Select Create a new branch for this commit and start a pull request. and click Propose file change.

  5. Click Create pull request.

    This initiates Cloud Build to build your code.

  6. Go to the Checks tab.

    Screenshot of the checks tab

    You'll see that Cloud Build has built your changes and you should see that your build has succeeded. You'll also see other build details such as the time it took to build your code, the build ID, etc.

  7. Click View more details on Google Cloud Build.

    The Build details page in GCP Console opens where you can see build information such as status, logs, and build steps.

  8. Go to the GitHub tab in your browser and go to the Conversation tab.

    Screenshot of the conversation tab

  9. Click Merge pull request and then Confirm merge.

    That's it! You've verified that your code changes builds correctly and checked in your changes.

Additional examples

Here are some sample repositories that contain code examples that use cloudbuild.yaml as the configuration file. You can fork the repos and use the steps described in this tutorial to build the code:

Cleaning up

After you've finished the tutorial, you can clean up the resources you created on Google Cloud Platform so they won't take up quota and you won't be billed for them in the future. The following sections describe how to delete or turn off these resources.

Uninstalling the Google Cloud Build app

  1. Go to the GitHub app page for Google Cloud Build.

    Open Cloud Build app page

  2. Click Configure.

  3. Select your username or organization where you installed the app.

  4. Click Uninstall.

Deleting the GitHub repository

  1. On GitHub, navigate to the main page of the repository.

    https://github.com/[GITHUB_USERNAME]/gcbapp-dockerfile-example
    
  2. Under your repository name, click Settings.

  3. Under Danger Zone, click Delete this repository.

  4. Type the name of your repository to confirm and then click I understand the consequences, delete this repository.

Deleting the container images

  1. Open the Container Registry page in the Google Cloud Platform Console.

    Open the Container Registry page

  2. Select your project and click Open.

  3. Open gcbapp-dockerfile-example.

  4. Select all the images and click Delete.

The images that you created as part of this tutorial are deleted from your project.

Deleting the project

The easiest way to eliminate billing is to delete the project you created for the tutorial.

To delete the project:

  1. In the GCP Console, go to the Projects page.

    Go to the Projects page

  2. In the project list, select the project you want to delete and click Delete delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next

  • Try out other Google Cloud Platform features for yourself. Have a look at our tutorials.
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Build Documentation