Cloud Build provides a Cloud Build GitHub app that allows you to automatically build your code each time you push a new commit to GitHub.
This tutorial explains how to install and configure the app, and how to automatically trigger builds on GitHub.
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 and publishes results to a pull request.
- View the build results on GitHub and the Cloud Console.
- Learn about the different ways to configure your builds.
This tutorial uses the following billable components of Google Cloud:
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.
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
- 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.
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
- Create a GitHub account if you don't have one already.
- Enable the Cloud Build API in the target Cloud project.
Preparing a GitHub repository with source files
To use the Google Cloud Build app, your repository must contain either a
cloudbuild.yaml file to configure
your build. Your
cloudbuild.yaml file can be located in
the root of your repository or in a sub-directory of your repository.
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
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.yamlin addition to the
Dockerfile. If your repository contains a
cloudbuild.yaml, the Google Cloud Build app will use the
cloudbuild.yamlto configure the builds.
If you wish to use the Google Cloud Build app for non-Docker builds.
Forking the example repository
To work through the example in this tutorial, you need a GitHub repository with some source code to build. We are providing a sample repository for this purpose that you must fork before continuing.
Use the following steps to fork the sample repository. The source
files in the repository include a
helloworld.sh file and a
you will use to build your Docker image.
On GitHub, navigate to /GoogleCloudBuild/gcbapp-dockerfile-example.
On the top-right corner of the page, click Fork.
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 Cloud project and set
up continuous integration for
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 Cloud Console where you'll select your Cloud 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.
If you have not already done so, enable the Cloud Build API in the target Cloud project.
Go to the GitHub marketplace page for the Google Cloud Build app.
Scroll down and click Setup with Google Cloud Build at the bottom of the page.
If prompted, sign in to GitHub.
In the Edit your plan page, select or update your billing information and click grant this app access. If you have previously purchased the GitHub Cloud Build app and are reinstalling it, skip this step.
Select one of the following options based on your business need:
All repositories - enable all current and future GitHub repositories for access via the Cloud Build app.
Only select repositories - use the Select repositories drop-down to only enable specific repositories for access via the Cloud Build app. You will be able to enable additional repositories at a later time.
Sign in to Google Cloud.
The Authorization page is displayed where you are asked to authorize the Google Cloud Build app to connect to Google Cloud Platform.
Click Authorize Google Cloud Build by GoogleCloudBuild.
You are redirected to the Cloud Console.
Select your Cloud project.
Check the consent checkbox and click Next.
In the Select repository page that appears, connect your GitHub repositories to your Cloud project as follows:
a. Confirm the correct GitHub account has been selected.
b. Select the checkbox next to each target repository.
c. Read the consent disclaimer and select the checkbox next to it to indicate that you accept the presented terms.
d. Click Connect repository.
If you don't see one or more of your target repositories, click Edit repositories on GitHub and repeat the steps above to enable additional repositories in the Cloud Build app.
If you wish to create one or more initial default trigger(s) that will trigger builds on any branch push, use the Create a push trigger page that appears to those triggers. Select the boxes next to each target repository and click Create push triggers. Otherwise, skip this step.
You now have successfully installed the Google Cloud Build app, connected your chosen repositories to your Cloud project, and created push triggers that will launch your build(s).
Connecting additional repositories
To connect additional repositories to your Cloud project , follow the steps below:
Select your GitHub account and click Continue.
Click Add another project.
Under Project settings, select your project or create a new project.
Click Connect repository.
Under Repository selection, select all repositories to connect with your project.
Optionally, under Trigger settings, select all repositories for which you would like to create a push trigger.
To create a trigger, click Create push trigger. Otherwise, click Skip for now to be taken back to your list of connected repositories.
Update the authenticated GitHub account
If you need to update the GitHub account associated with your Google account, you can navigate to the Authenticate with GitHub page. This may be necessary if you went thorugh the initial connect repository flow with a different account from your primary GitHub account. You may need to do this if you notice that the Cloud Build Connect Repository page indicates that the GitHub app is not installed on any repositories after installing the Cloud Build app on GitHub.
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 push a new commit to the repository. Builds for pushed commits included in pull requests will be included in the pull request UI.
Open helloworld.sh in
Click on the pencil icon to edit the file.
Add the following line at the end of the file:
echo "The time is $(date)."
Select Create a new branch for this commit and start a pull request. and click Propose file change.
Click Create pull request.
This initiates Cloud Build to build your code.
Go to 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.
Click View more details on Google Cloud Build.
The Build details page in Cloud Console opens where you can see build information such as status, logs, and build steps.
Go to the GitHub tab in your browser and go to the Conversation tab.
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.
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:
After you've finished the Cloud Build tutorial, you can clean up the resources that you created on Google Cloud 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.
Removing the connection between the repo and the Google Cloud Build app
To stop triggering builds using the Cloud Build app, remove the connection between your repository and the app using the steps below:
Go to your GitHub profile's settings page:
Login to your GitHub account.
Under Personal settings, click Applications.
Locate the row with Google Cloud Build, and click Configure.
Under Repository access, locate
[YOUR_GITHUB_USERNAME]/gcbapp-dockerfile-exampleand click X.
You will be redirected to Google Cloud.
Login to Google Cloud.
In the Cloud Build page, locate the connection between your Cloud project and
gcb-dockerfile-example, and click Unlink.
You've now removed the connection between
gcb-dockerfile-example and the Google
Cloud Build app, and Cloud Build will not trigger builds for the code
Uninstalling the Google Cloud Build app
Go to the GitHub app page for Google Cloud Build.
Select your username or organization where you installed the app.
Deleting the GitHub repository
On GitHub, navigate to the main page of the repository.
Under your repository name, click Settings.
Under Danger Zone, click Delete this repository.
Type the name of your repository to confirm and then click I understand the consequences, delete this repository.
Deleting the container images
Open the Container Registry page in the Google Cloud Console.
Select your project and click Open.
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 that you created for the tutorial.
To delete the project:
- In the Cloud Console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.