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 and build on GitHub using the Cloud Build GitHub app.

Before you begin

  • Enable the Cloud Build API.

    Enable the API

  • Have your source code ready in a GitHub repository.
  • Have either a Dockerfile or a Cloud Build config file in your GitHub source repository.
  • If you are initially connecting your repository to Cloud Build, make sure you have admin-level permissions on your repository. To learn more about GitHub repository permissions, see Repository permission levels for an organization.
  • To use gcloud commands on this page, install the Cloud SDK.

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.

    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 enable only 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 directed to a project selector page within Cloud Build. On this page, you can select an existing Cloud project or create a new project.

    If you do not see an existing project listed on this page, click Select Project to see a list of all existing projects.

  10. After you have selected a project or created a new one, you will see the Connect repository panel.

  11. In the Select repository section, select the following fields:

    • GitHub account: The GitHub account used to install the Cloud Build GitHub App. This field may be pre-selected for you.

    • Repository: The repositories you want to connect to Cloud Build.

      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 GitHub App.

  12. Once you have selected your GitHub account and repositories, read the consent disclaimer and select the checkbox next to it to indicate that you accept the presented terms.

  13. Click Connect.

  14. (Optional) In the Create a trigger section, select the repositories you want to create a trigger for in the Create a sample trigger for these repositories field. Once you have selected your repositories, click Create a trigger.

  15. Click Done.

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

(Optional) Updating 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. 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.

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 additional 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: If you selected Pull request (GitHub App only) as your Event, choose one of the following options to control whether a build will automatically be executed by the trigger:

        • Required except for owners and collaborators: When a pull request is created or updated by a repository owner or collaborator, builds will automatically be executed by the trigger. If an external contributor initiates the action, builds will only be executed after an owner or collaborator comments /gcbrun on the pull request.

        • Required: When a pull request is created or updated by any contributor, builds will only be executed after an owner or collaborator comments /gcbrun on the pull request.

        • Not required: When a pull request is created or updated by any contributor, builds will automatically be executed by triggers.

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

    • Configuration: Select the build config file located in your remote repository or create an inline build config file to use for your build.

      • Type: Select the type of configuration to use for your build.
        • Cloud Build configuration file (yaml or json): Use a build config file for your configuration.
        • Dockerfile: Use a Dockerfile for your configuration.
      • Location: Specify the location for your configuration.

        • Repository: If your config file is in located in your remote repository, provide the location of your build config file or the Dockerfile directory and a name for the resulting image. If your configuration is a Dockerfile, you can optionally provide a timeout for your build. When you've provided the Dockerfile and image name, you'll see a preview of the docker build command that your build will execute.
        • Inline: If you selected Cloud Build configuration file (yaml or json) as your configuration option, you can specify your build config inline. Click Open Editor to write your build config file in the Google Cloud Console using YAML or JSON syntax. Click Done to save your build config.

  6. Click Create to save your build trigger.

To create GitHub App triggers using gcloud commands, see the gcloud commands for Creating a build trigger.

Building and viewing your changes

To build using GitHub app triggers, you'll need to push and commit changes to your connected source repository or configure your build on pull requests. Once you have checked in your changes, Cloud Build will build your code.

To view your build changes on GitHub, go to the Checks tab in your repository.

Screenshot of the conversation tab

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

To view your build changes in Cloud Build, click on 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.

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

Data sharing

GitHub app triggers send data to the Cloud Build GitHub app. The data sent to the app helps you identify triggers by name and see build results on GitHub.

The following data is currently shared between Google Cloud and GitHub app:

  • Trigger name

If you created triggers prior to August 2020, data sharing may not be enabled for your project. You can enable data sharing for all GitHub app triggers in your project by clicking Enable on the Cloud Build Data sharing tab.

If you have required status checks enabled for a GitHub repository, enabling data sharing may temporarily break status checks. You can adjust status check configurations to look for your trigger name by:

  • Disabling any Cloud Build-specific required checks on the GitHub repository
  • Ensuring that data sharing is enabled in Cloud Build
  • Executing a new build in Cloud Build that posts statuses to your repository
  • Re-enabling required status checks, selecting trigger name

What's next