Manage build dependencies

This page explains how you can specify build dependencies. Cloud Build lets you manage source-code dependencies separately from the build process.

In your build configuration file, you can list one or more Git repositories to clone for your build, and the order in which to fetch them. Specifying dependencies in this way separates dependency fetching from the build process itself.

If you don't include any dependencies in your build configuration file, Cloud Build clones the source code repository that contains your build configuration file (for triggered builds) or the repository that contains your source code (for builds that you invoke from the command line). If you do include dependencies in your build configuration file, Cloud Build doesn't clone any repositories that aren't specified in the dependencies field.

Any source code repository you specify in the dependencies field must be connected to Cloud Build using Developer Connect, or else be a public repository.

Dependencies are cloned in the order that you specify them in this configuration. Also, dependency fetching occurs before any user-specified logic is executed. Thus, dependency fetching is trusted.

Dependencies are shown in the Build dependencies tab of the Build details page.

Before you begin

The instructions on this page assume that you have one or more Git repositories that are either public repositories or are linked using Developer Connect.

To get the permissions that you need to add a Developer Connect repository as a dependency, ask your administrator to grant you the Developer Connect Read Token Accessor (developerconnect.readTokenAccessor) IAM role on your service account. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Specify dependencies

You specify dependencies by adding a dependencies stanza to your build configuration file. dependencies is a top-level property in the build config, but you can put it anywhere in the file.

The following is the syntax for the dependencies stanza:

YAML 

 dependencies:
 - gitSource:
     repository:
       url: 'URL'
       developerConnect: 'RESOURCE_PATH'
     revision: 'REVISION'
     recurseSubmodules: 'true|false'
     depth: DEPTH'
     destPath: 'DEST_PATH'

JSON 

 {
     "dependencies": {
         "gitSource": {
             "repository": {
                 "url": "URL"
                 "developerConnect": "RESOURCE_PATH"
             },
             "revision": "REVISION",
             "recurseSubmodules": true|false,
             "depth": "DEPTH",
             "destPath": "DEST_PATH",
         },
     },
 }

You must specify either a URL or a resource path. Specify a resource path if the repository to fetch is connected to Cloud Build using Developer Connect.

Replace the following values:

  • URL: Optional. The HTTPS URL of the repository to fetch.

  • RESOURCE_PATH: Optional. The Google Cloud resource path to a Developer Connect repository. For example, projects/my-project/locations/us-central1/connections/my-connection/gitRepositoryLinks/my-repo.

  • REVISION: Required. The version, commit hash, tag, or branch name to fetch from the repository.

  • recurseSubmodules: 'true|false': Whether to fetch submodules.

  • DEPTH: Optional, how deep into the repository history to fetch. If not specified, the latest commit is fetched.

    • 1: the latest commit
    • 2: the last two commits
    • 3: the last three commits
    • -1: all commits

  • DEST_PATH: Required. The path to the directory into which the repository is cloned. For example, my/repo.

    When you set the dest_path the repository is fetched in /workspace/<dest_path>. The dest_path value must be a path relative to the working directory of the build.

Specify a Developer Connect repository as a dependency

  • If you specify a Developer Connect repository as a dependency, then you must grant the Developer Connect Read Token Accessor role to the Cloud Build service account. For more information, see Grant Cloud Build access to a Developer Connect repository.

  • Your build must be in the same region as the Developer Connect connection.

What's next