Cloud Build client libraries

This page shows how to get started with the Cloud Client Libraries for the Cloud Build API. However, we recommend using the older Google API Client Libraries if running on Google App Engine standard environment. Read more about the client libraries for Cloud APIs in Client Libraries Explained.

Install the client library

C++

See Setting up a C++ development environment for details about this client library's requirements and install dependencies.

Go

For more information, see Setting Up a Go Development Environment.

go get cloud.google.com/go/cloudbuild

Java

For more information, see Setting Up a Java Development Environment.

If you are using Maven, add this to your pom.xml file:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-build</artifactId>
    <version>3.8.0</version>
</dependency>

If you are using Gradle, add this to your dependencies:

compile group: 'com.google.cloud', name: 'google-cloud-build', version: '3.8.0'

Node.js

For more information, see Setting Up a Node.js Development Environment.

npm install --save @google-cloud/cloudbuild

Python

For more information, see Setting Up a Python Development Environment.

pip install --upgrade google-cloud-build

Set up authentication

When you use client libraries, you use Application Default Credentials (ADC) to authenticate. For information about setting up ADC, see Provide credentials for Application Default Credentials. For information about using ADC with client libraries, see Authenticate using client libraries.

Use the client library

The following example shows how to use the client library.

C++

To authenticate to Cloud Build, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


#include "google/cloud/cloudbuild/v1/cloud_build_client.h"
#include <iostream>

int main(int argc, char* argv[]) try {
  if (argc != 2) {
    std::cerr << "Usage: " << argv[0] << " project-id\n";
    return 1;
  }

  namespace cloudbuild = ::google::cloud::cloudbuild_v1;
  auto client =
      cloudbuild::CloudBuildClient(cloudbuild::MakeCloudBuildConnection());
  auto const* filter = R"""(status="WORKING")""";  // List only running builds
  for (auto b : client.ListBuilds(argv[1], filter)) {
    if (!b) throw std::move(b).status();
    std::cout << b->DebugString() << "\n";
  }

  return 0;
} catch (google::cloud::Status const& status) {
  std::cerr << "google::cloud::Status thrown: " << status << "\n";
  return 1;
}

Node.js

To authenticate to Cloud Build, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

async function quickstart(
  projectId = 'YOUR_PROJECT_ID', // Your Google Cloud Platform project ID
  triggerId = 'YOUR_TRIGGER_ID', // UUID for build trigger.
  branchName = 'BRANCH_TO_BUILD' // Branch to run build against.
) {
  // Imports the Google Cloud client library
  const {CloudBuildClient} = require('@google-cloud/cloudbuild');

  // Creates a client
  const cb = new CloudBuildClient();

  // Note: for Private Pools, you'll have to specify an API endpoint value
  // For example:
  // const cb = new CloudBuildClient({ apiEndpoint: '<YOUR_POOL_REGION>-cloudbuild.googleapis.com' });

  // Starts a build against the branch provided.
  const [resp] = await cb.runBuildTrigger({
    projectId,
    triggerId,
    source: {
      projectId,
      dir: './',
      branchName,
    },
  });
  console.info(`triggered build for ${triggerId}`);
  const [build] = await resp.promise();

  const STATUS_LOOKUP = [
    'UNKNOWN',
    'Queued',
    'Working',
    'Success',
    'Failure',
    'Error',
    'Timeout',
    'Cancelled',
  ];
  for (const step of build.steps) {
    console.info(
      `step:\n\tname: ${step.name}\n\tstatus: ${STATUS_LOOKUP[build.status]}`
    );
  }
}

Python

To authenticate to Cloud Build, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import google.auth
from google.cloud.devtools import cloudbuild_v1


def quickstart() -> None:
    """Create and execute a simple Google Cloud Build configuration,
    print the in-progress status and print the completed status."""

    # Authorize the client with Google defaults
    credentials, project_id = google.auth.default()
    client = cloudbuild_v1.services.cloud_build.CloudBuildClient()

    # If you're using Private Pools or a non-global default pool, add a regional
    # `api_endpoint` to `CloudBuildClient()`
    # For example, '<YOUR_POOL_REGION>-cloudbuild.googleapis.com'
    #
    # from google.api_core import client_options
    # client_options = client_options.ClientOptions(
    #     api_endpoint="us-central1-cloudbuild.googleapis.com"
    # )
    # client = cloudbuild_v1.services.cloud_build.CloudBuildClient(client_options=client_options)

    build = cloudbuild_v1.Build()

    # The following build steps will output "hello world"
    # For more information on build configuration, see
    # https://cloud.google.com/build/docs/configuring-builds/create-basic-configuration
    build.steps = [
        {"name": "ubuntu", "entrypoint": "bash", "args": ["-c", "echo hello world"]}
    ]

    operation = client.create_build(project_id=project_id, build=build)
    # Print the in-progress operation
    print("IN PROGRESS:")
    print(operation.metadata)

    result = operation.result()
    # Print the completed status
    print("RESULT:", result.status)

Additional resources