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.

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,

Required roles

If any repository you're adding as a dependency is a Developer Connect repository, your service account needs the Developer Connect Read Token Accessor role:

This is in addition to any other Cloud Build roles you need.

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",
         },
     },
 }

Replace the following values:

  • URL: Optional. The HTTPS URL of the repository to fetch. You must specify either a URL or a Developer Connect resource path.

  • RESOURCE_PATH: Optional. The Google Cloud resource path to that Developer Connect repository. For example, projects/my-project/locations/us-central1/connections/my-connection/gitRepositoryLinks/my-repo. You must specify either a URL or a Developer Connect resource path. Specify this field if the repository to fetch is connected to Cloud Build using Developer Connect.

  • 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 will be cloned. For example, my/repo.

    When you set the dest_path the repo will be fetched in /workspace/<dest_path>. The dest_path value must be a relative path, and it is relative to the build's working directory.

Specify a Developer Connect repository as a dependency

  • If you specify a Developer Connect repository as a dependency, 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