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 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 include dependencies in your build configuration file, Cloud Build clones only repositories that are specified in the dependencies field.

Dependencies are cloned in the order that you specify them. 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 at least one of the following two repository types:

  • A Git repository that is either a public repository or linked to Cloud Build using Developer Connect.

  • A generic repository.

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

Your administrator might also be able to give the required permissions through custom roles or other predefined roles.

Specify dependencies

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

Specify GitHub dependencies

To specify a dependency on a GitHub repository, add the following dependencies configuration to your build config file:

YAML 

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

JSON 

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

Replace the following values:

  • URL: The HTTPS URL of the repository to fetch. Required unless your repository is connected to Cloud Build using Developer Connect.

  • DC_RESOURCE_PATH: The Google Cloud resource path to a Developer Connect repository. For example, projects/my-project/locations/us-central1/connections/my-connection/gitRepositoryLinks/my-repo. Required if your repository is connected to Cloud Build using Developer Connect.

    If your repository is connected using Developer Connect, you need the following:

  • 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 generic artifact as a dependency

To specify a generic artifact as a dependency, add the following dependencies configuration to your build config file:

YAML 

dependencies:
- genericArtifact:
    resource: RESOURCE
    destPath: PATH

JSON 

{
  "dependencies": [
    {
      "genericArtifact": {
        "resource": "RESOURCE",
        "destPath": "PATH"
      }
    }
  ]
}

Where:

  • RESOURCE is the full address of the generic artifact within your Artifact Registry generic repository, formatted as follows:

    projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION

    We strongly recommend including your artifact's fingerprint in the resource address so that Cloud Build can verify that the artifact reference is immutable. A package version with an appended fingerprint is formatted as follows:

    VERSION@dirsum_sha256=HASH_VALUE

    To find the fingerprint of an artifact in an Artifact Registry repository, see Retrieve the fingerprint of a package version in your repository.

  • PATH is the address to the folder to which Cloud Build downloads the package from your repository. If the folder doesn't exist yet, Cloud Build creates it automatically.

What's next