Creating GitHub App triggers

GitHub App triggers enable you to automatically invoke builds on Git pushes and pull requests, and view your build results on GitHub and Cloud Console. Additionally, GitHub App triggers support all the features supported by the existing GitHub triggers and use the Cloud Build GitHub app to configure and authenticate to GitHub.

This page explains how to create GitHub App triggers.

Creating GitHub App triggers

This section explains how to install the Cloud Build GitHub App to connect your GitHub repository to your Cloud project and then create GitHub App triggers.

Installing the Cloud Build app

To install the Cloud Build app and connect your GitHub repository to your Cloud project:

  1. Open the Triggers page in the Google Cloud Console.

    Open the Triggers page

  2. In the project selector in the top bar, select your Cloud project.

  3. Click Connect repository.

  4. Select GitHub (Cloud Build GitHub App), check the consent checkbox, and click Continue.

  5. (Optional) If you have not signed into GitHub before, do so now.

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

    Screenshot of the authorize button

    Click Authorize Google Cloud Build by GoogleCloudBuild.

  6. Click Install Google Cloud Build.

  7. In the pop-up that appears, select your GitHub username or organization.

  8. 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.

  9. Click Install to install the Cloud Build app.

    The pop-up closes and you are returned to the Select repository page in the Cloud Console. In this page you will connect your GitHub repositories to your Cloud project.

  10. 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.

  11. (Optional) To create push triggers for the repositories you're connecting, select the boxes next to each target repository and click Create push triggers; otherwise, click Skip for now.

    You have now connected one or more GitHub repositories to your Cloud project. You are directed to the Triggers page in Cloud Console.

Creating GitHub App triggers

To create GitHub App triggers:

  1. Open the Triggers page in the Google Cloud Console.

    Open the Triggers page

  2. Select your project from the project selector drop-down menu at the top of the page.

  3. Click Open.

  4. Click Create trigger.

  5. Enter the following trigger settings:

    • Name: Enter a name for your trigger.

    • Description (optional): Enter a description for your trigger.

    • Event: Select the repository event to invoke your trigger.

      • Push to a branch: Set your trigger to start a build on commits to a particular branch.

      • Push new tag: Set your trigger to start a build on commits that contain a particular tag.

      • Pull request (GitHub App only): Set your trigger to start a build on commits to a pull request.

    • Source: Select the repository and the corresponding branch or tag to watch for events.

      • Repository: From the list of available repositories, select the desired repository. To connect a new repository, see Connecting to source repositories.

      • Branch or Tag: Specify a regular expression with the branch or tag value to match. For information on acceptable regular expression syntax, see RE2 syntax.

      • Comment control (optional): If you selected Pull request (GitHub App only) as your Event, check the box to control whether builds can only start if a repository owner or collaborator comments /gcbrun.

    • Included files (optional): Changes affecting at least one of these files will invoke a build.

    • Ignored files (optional): Changes only affecting ignored files will not invoke a build.

    • Build configuration: Select the build config file (located in the GitHub repository connected to your Cloud project) to use for your build.

      • To use a Dockerfile for your build configuration, you'll need to specify the Dockerfile directory and a name for the resulting image. When you've provided the Dockerfile and image name, you'll see a preview of the docker build command that your build will execute and a summary of the trigger configuration.

      • To use a build config file for your build configuration, you'll need to provide the location of your build config file and optionally, substitution variables you'll want to use.

  6. Click Create to save your build trigger.

Different types of GitHub-based triggers

If your source code is in GitHub, Cloud Build provides two ways by which you can automatically invoke builds. This section explains the two GitHub-based triggers and compares their features.

  • GitHub triggers: When you create a GitHub trigger, Cloud Build mirrors your GitHub repository in Cloud Source Repositories and uses the mirrored repository for all its operations. You can create and manage GitHub triggers using the Cloud Console.

  • GitHub App triggers: This type of trigger uses the Cloud Build GitHub app to configure and authenticate to GitHub. GitHub App triggers allow you to automatically start builds on Git pushes and pull requests and view build results on GitHub and Cloud Console. You can create and manage GitHub App triggers using Cloud Console or the Cloud Build API.

The following table compares the features of GitHub triggers and GitHub App triggers:

Feature GitHub triggers GitHub App triggers
Invoke builds on pushes to the source code Yes Yes
Invoke builds on pull requests No Yes
Create trigger using Cloud Console Yes Yes
Create trigger using the Cloud Build API No Yes
Create trigger using the Cloud Build GitHub app No Yes
View build status on Cloud Console Yes Yes
View build status on GitHub No Yes

What's next