Automating builds with Cloud Build

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

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 the cloudbuild.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

  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.

    • Source: Select the repository and the corresponding branch or tag to watch for events.

      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 a Dockerfile 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 the Dockerfile or buildpack image name, you'll see a preview of the docker build or pack 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.

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

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