Creating and managing build triggers

A Cloud Build trigger automatically starts a build whenever you make any changes to your source code. You can configure the trigger to build your code on any changes to the source repository or only changes that match certain criteria.

This page explains how to connect to source repositories such as GitHub and Bitbucket, and create build triggers to build the code in the repositories.

Before you begin

  • You need source code in Cloud Source Repositories, GitHub, or Bitbucket.
  • You need either a Dockerfile or a Cloud Build config file.

Connecting to source repositories

You must first connect Cloud Build to your source repository before building the code in that repository. Your repositories in Cloud Source Repositories are connected to Cloud Build by default; you can directly create triggers for your repositories in Cloud Source Repositories without manually connecting to them. Use the following steps to connect to GitHub and Bitbucket:

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

    Open the triggers page

  2. Select your project and click Open.

  3. Click Connect Repository.

  4. Select the repository where you've stored your source code.

    If you select GitHub (mirrored) or Bitbucket (mirrored) as your source repository, Cloud Build mirrors your repository in Cloud Source Repositories and uses the mirrored repository for all its operations.

  5. Click Continue.

  6. Authenticate to your source repository with your username and password.

  7. From the list of available repositories, select the desired repository, then click Connect repository.

    For external repositories, such as GitHub and Bitbucket, you must have owner-level permissions for the Cloud project with which you're working.

  8. Click Add trigger to continue creating a build trigger to automate builds for the source code in the repository, or click Done.

Creating a build trigger

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.

    • 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. This feature is only available if you create a GitHub App trigger. To learn how to create a GitHub App trigger, see Creating GitHub App triggers.

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

    • Included files (optional): Changes affecting at least one of these files will invoke a build. You can use glob strings to specify multiple files with wildcard characters. Acceptable wildcard characters include the characters supported by Go Match, **, and alternation.

    • Ignored files (optional): Changes only affecting ignored files will not invoke a build. You can use glob strings to specify multiple files with wildcard characters. Acceptable wildcard characters include the characters supported by Go Match, **, and alternation.

      If you specify a file in both Included files and Ignored files, changes to that file will not invoke a build. Say you specify **/README.md in Ignored files to ignore README.md in any directory, and specify src/* in Included files to start a build on changes to any file in the folder src/. Now if you make a change to src/README.md, Cloud Build will not start a build. Each time you push a change to your source, Cloud Build looks through your changed files for included and ignored files to determine whether a build should be invoked:

      • If you push a change to your repository on an existing branch, Cloud Build looks at the files changed between the commit you just pushed and the commit to which the branch previously pointed.
      • If you push a change to a newly created branch, then Cloud Build treats all the files in the repository as changed files.
      • If you delete a branch, Cloud Build does not start a build.
    • Build configuration: Select the build config file (located in the remote repository) 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. Optionally, you can also 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.

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

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

  6. Click Create to save your build trigger.

gcloud

To create a trigger if your source code is in Cloud Source Repositories:

    gcloud beta builds triggers create cloud-source-repositories \
    --repo=[REPO_NAME] \
    --branch-pattern=".*" \
    --build-config=[BUILD_CONFIG_FILE] \

Where:

  • --repo is the name of your repository.
  • --branch-pattern is your trigger type specified as a string. In the example above, we specify ".*", which indicates that a build will be triggered when changes are pushed to any branch in the repository. You can also use --tag-pattern to indicate that builds will only be triggered when pushed to specific tags.
  • --build-config is the path to your build configuration file.

For a complete list of flags, see the gcloud reference for how to create triggers for Cloud Source Repositories.

To create a trigger if your source code is in GitHub:

    gcloud beta builds triggers create github \
    --repo-name=[REPO_NAME] \
    --repo-owner=[REPO_OWNER] \
    --branch-pattern=".*" \
    --build-config=[BUILD_CONFIG_FILE] \

Where:

  • --repo-name is the name of your repository.
  • --repo-owner is the name of the repository's owner.
  • --branch-pattern is your trigger type specified as a string. In the example above, we specify ".*", which indicates that a build will be triggered when changes are pushed to any branch in the repository. You can also use --tag-pattern to indicate that builds will be only be triggered when pushed to specific tags or --pull-request-pattern to indicate the base git branch to match all pull request events.
  • --build-config is the path to your build configuration file.

For a complete list of flags, see the gcloud reference for how to create triggers for GitHub.

After you run the gcloud command to create a trigger using Cloud Source Repositories or GitHub, you should see an output similar to the following:

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

Testing a build trigger

To manually test a build trigger:

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

    Open the triggers page

  2. Locate your trigger in the list and then click Run trigger.

Skipping a build trigger

In some cases, you may want to make a change to your source code but you don't want to invoke a build. For example, you might not want to invoke a build when you update documentation or configuration files.

In such scenarios, you can include [skip ci] or [ci skip] in the commit message, and a build will not be invoked.

If you want to run a build on that commit later, use the Run trigger button in the Triggers page.

Including the repository history in a build

To build your source on a Git repo, Cloud Build performs a shallow clone of the repo. This means that only the single commit that started the build is checked out in the workspace to build. Cloud Build does not check out any other branches or history. This is done for efficiency, so that builds don't have to wait to fetch the whole repository and history just to build a single commit.

If you want to include more of your repo's history in the build, add a build step in your build config file to "unshallow" the clone. For example:

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

For more information on git fetch, see git reference. For instructions on writing a build config file, see Build config overview.

Disabling a build trigger

Console

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

    Open the Build triggers page

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

  3. Click Open.

  4. Locate the row with the trigger you would like to disable.

  5. Click on the menu (vertical ellipses) located at the right end of the row.

  6. Select Disable.

gcloud

To disable a trigger:

  1. Export the trigger you would like to disable:

     gcloud beta builds triggers export [NAME] --destination=[PATH]
    

    Where:

    • [NAME] is the name of your trigger.
    • [PATH] is the filepath you want to export your trigger to. For example, you can specify your filepath as examples/trigger.yaml. Note that the filename for your trigger should have the .yaml extension.
  2. Open the file containing your exported trigger.

    Your file will look similar to the following:

     createTime: '2020-02-21T20:02:50.215599013Z'
     description: Push to any branch
     filename: cloudbuild.yaml
     github:
       name: example-repo-name
       owner: example-owner
       push:
         branch: .*
     id: example-id
     name: Push-to-any-branch
     tags:
     - github-default-push-trigger
    
  3. Add the disabled field to the end of your file and set the value to True.

     disabled: True
    
  4. Save your file.

  5. Import your trigger:

     gcloud beta builds triggers import --source=[PATH]
    

    Where:

    • [PATH] is the filepath of your trigger that you would like to import.

Your build trigger is now disabled.

Disabling a trigger does not delete the trigger. To delete a trigger, see Deleting a build trigger. A trigger can be re-enabled by changing the status to Enabled.

Deleting a build trigger

Console

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

    Open the Build triggers page

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

  3. Click Open.

  4. Locate the row with the trigger you would like to delete.

  5. Click on the menu (vertical ellipses) located at the right end of the row.

  6. Select Delete.

gcloud

To delete a trigger, run the following command:

  gcloud beta builds triggers delete [NAME]

Where:

  • [NAME] is the name of your trigger.

For a complete list of flags, see the gcloud reference for how to delete triggers.

Security implications of build triggers

Build triggers use the Cloud Build account to execute builds, which could provide build-time permissions to users who use triggers to execute a build. Keep the following security implications in mind when using build triggers:

  • A user with no access to your Cloud project, but with write access to the repository associated with build triggers in the project will have permissions to change the code being built.
  • If you're using GitHub pull request triggers, any user with read access to the repository can submit a pull request, which may execute a build that includes changes to the code in the pull request. To learn how you can disable this behavior for GitHub pull request triggers, see Creating GitHub App triggers.

To learn more about the Cloud Build service account and it's associated permissions, see Cloud Build service account.

What's next