A build trigger instructs Cloud Build to automatically build your image whenever there are changes pushed to the build source. You can set a build trigger to re-build your images on any changes to the source repository, or only changes that match certain criteria.
Build triggers can help ensure that your container images are always based on the latest version of their source code. They're also useful for building and testing feature branches prior to release or for automating the workflows that produce your container images.
This page explains how to create build triggers.
Before you begin
- You need source code in Cloud Source Repository, GitHub, or Bitbucket.
- You need either a
Dockerfileor a Cloud Build build config file.
Creating a build trigger
To create a new build trigger:
Open the Build Triggers page in the Google Cloud Platform Console.
Select your project and click Open.
Click Add trigger.
Select one of the following host repositories for your build source:
- Cloud Source Repository
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 triggered 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'] ...
From the list of available repositories, select the desired repository, then click Continue.
Enter the following trigger settings:
Name (optional): An name for your trigger.
Trigger Type: You can set a trigger to start a build on commits to a particular branch, or on commits that contain a particular tag. In either case, you can 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 to these files will trigger 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 to these files will not trigger 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.
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 triggered:
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 or tag, then Cloud Build treats all the files in the repository as changed files.
If you delete a branch or a tag, Cloud Build does not trigger a build.
Build Configuration: The
Dockerfileor build config file (located in the remote repository) to use for each build that the trigger starts.
To use a Dockerfile for your build configuration, you'll need to specify the Dockerfile directory and supply a name for the resulting image.
When you've provided the Dockerfile and image name, you'll see a preview of the
docker buildcommand that your build will execute and a summary of the trigger configuration. Click Create trigger to save the build trigger.
To use a build config file for your build configuration, you'll need to provide the location of a build config file.
Once you've set the location, you'll see a summary of the trigger. Click Create trigger to save the build trigger.
Note: You can use built-in variables in the build config file.
Testing a build trigger
To manually test a build trigger, click Run trigger on your trigger's entry in the triggers list.
Skipping a build trigger
In some cases, you may want to make a change to your source code but you don't want to trigger a build. For example, you might not want to trigger 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 triggered.
If you want to run a build on that commit later, use the Run trigger button.
- Learn how to start builds manually in Cloud Build.