Building repositories from GitHub

1st gen 2nd gen

GitHub triggers enable you to automatically build on Git pushes and pull requests and view your build results on GitHub and Google Cloud console.

This page explains how to create GitHub triggers and build repositories from GitHub using the Cloud Build GitHub app. Learn more about Cloud Build triggers and Cloud Build repositories.

Before you begin

• Enable the Cloud Build API.

  Enable the API

• Follow instructions in Connect to a GitHub repository to install the Cloud Build GitHub app.

Creating a GitHub trigger

Console

To create GitHub triggers using the Google Cloud console:

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.

   • Region: Select the region for your trigger.

     • If you select global as the region, Cloud Build uses the default pool to run your build.
     • If you select a non-global region and the build config file associated with the trigger specifies a private pool, Cloud Build uses the private pool to run your build. In this case, the region you specify in your trigger must match the region where you created your private pool.
     • If you select a non-global region and the build config file associated with the trigger does not specify a private pool, Cloud Build uses the default pool to run your build in the same region as 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: Set your trigger to start a build on commits to a pull request.

         Note: Running builds initiated by a GitHub App pull request trigger will be canceled when you close the pull request associated with your build. Running builds and builds that have not been started yet will not be canceled when merging a pull request.

     • Source: Select 1st generation as your source.

       Note: The region of your repository must match the region of your trigger.

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

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

         Warning: Any user with read access to the repository can submit a pull request, which may execute a build that includes changes to the source code in the pull request. To disable this behavior, we recommend using manual approvals to gate builds when making pull requests on public repositories. For more information on build-time privileges of triggers, see Build triggers and Cloud Build service account.

         • 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 a repository owner or collaborator with /gcbrun in the pull request description or comment, builds will automatically be executed by the trigger. 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.

       Note: Included files and Ignored files can only be specified if you selected Push to a branch as your Event. For more information on Included files and Ignored files see the Console tab under Creating a build trigger.

     • 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.
         • Autodetected: Cloud Build autodetects your configuration type if you have a cloudbuild.yaml or Dockerfile in your repository.
         • Cloud Build configuration file (yaml or json): Use a build config file for your configuration.
         • Dockerfile: Use a Dockerfile for your configuration.
         • Buildpacks: Use buildpacks for your configuration.

       • Location: Specify the location for your configuration.

         • Repository: If your config file is 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.
         Note: Inline build configuration support is not available for Dockerfile.

     • Substitution variables (optional): If you selected the Cloud Build config file as your build config option, you can choose to define trigger-specific substitution variables using this field. For example, say you're creating multiple triggers where each trigger deploys your app to a specific environment. You can specify that your app is deployed to an environment in your build config file and then use this field to define substitution variables specifying which environment this trigger should deploy to. For information on specifying substitution values in build config files, see Substituting variable values.

     • Build logs (optional): Check the box to send build logs to GitHub. To learn how to view build logs, see Viewing build logs.

     • Service account: Select the service account to use when invoking your trigger. If you do not select a service account, the default Cloud Build service account is used.

       Note: Only the service account specified on your trigger will be used for builds executed by triggers. If you specified a service account in your build config, it will be ignored during build execution when using triggers.

   • Click Create to save your build trigger.

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

gcloud

To create GitHub triggers using gcloud commands, run the following command:

gcloud builds triggers create github \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --region=REGION \
    --include-logs-with-status

Where:

• REPO_NAME is the name of your repository.
• REPO_OWNER is the username of the repository owner.
• BRANCH_PATTERN is the branch name in your repository to invoke the build on.
• TAG_PATTERN is the tag name in your repository to invoke the build on.
• BUILD_CONFIG_FILE is the path to your build configuration file.
• REGION is the region for of your trigger.
• [OPTIONAL] --include-logs-with-status is a flag you can specify to show build logs for your repositories. This flag is supported for builds from GitHub and GitHub Enterprise repositories. To learn how to view build logs, see Viewing build logs.

Note: You can only use the --include-logs-with-status flag when creating a GitHub or GitHub Enterprise trigger using gcloud. Cloud Build does not currently support the functionality for creating a trigger using the Google Cloud console. To learn how to update your trigger to include or remove the flag, see Updating a build trigger.

Building and viewing your changes

To build using GitHub 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.

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 Google 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 execute builds. This section explains the two GitHub-based triggers and compares their features.

• GitHub legacy triggers: When you create a GitHub legacy 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 Google Cloud console.

  Note: If you are using GitHub legacy triggers, you will need to grant access to individual organizations via GitHub to use GitHub legacy triggers.

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

• GitHub Enterprise triggers: This type of trigger enables you to invoke builds in response to commits or pull requests on a GitHub Enterprise instance. You can build repositories from GitHub Enterprise using the Google Cloud console or the Cloud Build API.

The following table compares GitHub legacy triggers, GitHub triggers, and GitHub Enterprise triggers:

Feature	GitHub legacy triggers	GitHub triggers	GitHub Enterprise triggers
Execute builds on pushes to the source code	Yes	Yes	Yes
Execute builds on pull requests	No	Yes	Yes
Create trigger using Google Cloud console	Yes	Yes	Yes
Create trigger using the Cloud Build API	No	Yes	Yes
Create trigger using the Cloud Build GitHub app	No	Yes	Yes
View build status on Google Cloud console	Yes	Yes	Yes
View build status on GitHub	No	Yes	Yes

Data sharing

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

The following data is currently shared between Cloud Build and GitHub:

• Cloud project ID
• Trigger name
• Build logs

Note: Build logs are only shared if you configure your trigger to send build logs.

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

Note: Enabling data sharing for a project is not reversible.

What's next

• Learn how to create and manage build triggers.
• Learn how to perform blue/green deployments on Compute Engine.