This topic describes how to automate builds using Cloud Build and Cloud Source Repositories.
You can configure Cloud Build to automatically build a new image any time a user pushes a change to files stored in Cloud Source Repositories. Events that initiate automatic builds are called build triggers. These triggers can help ensure that your container images are kept up to date. You can also use them to build and test feature branches.
Build triggers can perform a build based on either a Dockerfile or a build config file.
Using a Dockerfile
To use a Dockerfile for your build configuration, you'll need to specify the Dockerfile directory and supply a name for the resulting image. For details about creating Dockerfiles, see the Docker documentation.
After you provide the Dockerfile and image name, you'll see a preview of the
docker build
command that your build executes and a summary of the trigger
configuration.
Using a build config file
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.
Before you begin
Enable the Cloud Build API.
Ensure you have source code in Cloud Source Repositories.
Ensure you have either a Dockerfile or a build config file.
If using a service account other than the default Cloud Build service account, see the Cloud Build page on Configuring user-specified service accounts.
Additional information
Build triggers use shallow clones of a repository. With shallow clones, only the single commit that triggered an automatic build is checked out in the workspace. For more information, and to learn how to include more of your repositories history, see Unshallowing clones.
If you use another hosted Git provider, such as on GitHub or Bitbucket, and still need to mirror the repository into Cloud Source Repositories, you must have the
cloudbuilds.builds.create
permission for the Google Cloud project with which you're working. This permission is typically granted through thecloudbuild.builds.editor
role.When you set up a build trigger with an external repository for the first time, you'll need to set up authorization with that repository. For more information, see Adding a repository as a remote.
After you set up your external repository, Cloud Source Repositories creates a mirror of your repository.
For information on the quotas and limits for Cloud Build, see Quotas and limits in the Cloud Build documentation.
Create a build trigger
Console
Open the Triggers page in the Google Cloud console.
Select your project from the project selector drop-down menu at the top of the page.
Click Open.
Click Create trigger.
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.
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.
When your build executes, the contents of your repository will be copied to
/workspace
, the default working directory used by Cloud Build. Learn more about working directories on the Build configuration overview page.- Branch or Tag: Specify a regular expression with the branch or
tag value to match. Forward slashes (
/
) cannot be used in tags. For more information on acceptable regular expression syntax, see RE2 syntax.
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. - 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, the
Dockerfile
directory, or the buildpacks directory. If your build config type is aDockerfile
or a buildpack, you will need to provide a name for the resulting image and optionally, a timeout for your build. When you've provided theDockerfile
or buildpack image name, you'll see a preview of thedocker build
orpack
command that your build will execute. - Buildpack environment variables (optional): If you
selected
buildpacks
as your configuration type, click Add pack environment variable to specify your buildpack environment variables and values. To learn more about buildpack environment variables, see Environment variables. 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.
- Repository: If your config file is located in your
remote repository, provide the location of your
build config file, the
- Type: Select the type of configuration to use for your build.
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.
Click Create to save your build trigger.
gcloud
Run the following command:
gcloud beta builds triggers create cloud-source-repositories \
--repo=REPO_NAME \
--branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
--build-config=BUILD_CONFIG_FILE \
--service-account=SERVICE_ACCOUNT \
--require-approval
Where:
- REPO_NAME is the name of your repository.
- 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.
- SERVICE_ACCOUNT (preview) is the email associated with your service account. If you don't include this flag, the default Cloud Build service account is used.
- [Optional]
--require-approval
is the flag to include to configure your trigger to require approval.
For a complete list of flags, see the gcloud
reference for how to create triggers
for Cloud Source Repositories.
After you run the gcloud
command to create a trigger using
Cloud Source Repositories, you should see an output similar to the
following:
NAME CREATE_TIME STATUS
trigger-001 2019-10-30T20:45:03+00:00
View build triggers
To view triggers in the Google Cloud console, open the Cloud Build Triggers page.
To view triggers for a given project in Cloud Source Repositories, click Settings
in the top-right, then click Cloud Build Triggers.Skip a build trigger
In some cases, you might want to change your source code but don't want to trigger a build, for example, when you update documentation or configuration files.
In such cases, you can include [skip ci]
or [ci skip]
in the commit message,
and a build will not be triggered.
For example:
Author: A User <auser@example.com>
Date: Tue Apr 3 12:03:35 2018 -0700
Fixed customer affecting issue. [skip ci]
If you want to run a build on that commit later, use the Run trigger button.
Unshallowing clones
To build your source on a Git repository, Cloud Source Repositories performs a shallow clone of the repository. When Cloud Source Repositories performs a shallow clone, it checks out from the workspace only the single commit that triggered the build, and then it builds from that source. Cloud Source Repositories doesn't check out any other branches or history. This is done for efficiency. Builds aren't delayed while Cloud Source Repositories fetches the whole repository and history just to build from a single commit.
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.
What's next
- Learn how to start builds manually in Cloud Build.
- Learn more about building, testing, and deploying artifacts.