Registry / gcp / google-cloud-build

google-cloud-build

library3.35.0pypypi✓ verified 47d ago

The `google-cloud-build` client library provides Python APIs to interact with Google Cloud Build, a service that executes your builds on Google Cloud Platform infrastructure. It allows users to define custom workflows for building, testing, and deploying across various environments. The library is currently at version 3.35.0 and is part of the Google Cloud Python client libraries, which receive frequent updates across their various service clients, often on a weekly or bi-weekly basis for individual clients.

gcp devops

pip install google-cloud-build

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v3.37.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

4/5 runs

py 3.11

4/5 runs

py 3.12

4/5 runs

py 3.13

4/5 runs

py 3.9

4/5 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CloudBuildClient

✓ from google.cloud.devtools.cloudbuild_v1 import CloudBuildClient

✗ from google.cloud import build_v1

This quickstart initializes the Cloud Build client and lists recent builds for a specified Google Cloud project. Ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set or replace 'your-gcp-project-id' with your project ID. The Cloud Build API must be enabled, and your credentials must have the `cloudbuild.builds.list` permission.

import os from google.cloud import build_v1 from google.api_core.exceptions import GoogleAPIError project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id') try: # Initialize the Cloud Build client client = build_v1.CloudBuildClient() # List recent builds for the specified project print(f"Listing recent builds for project: {project_id}") request = build_v1.ListBuildsRequest(project_id=project_id) builds = client.list_builds(request=request) if not builds.builds: print("No builds found.") else: for build in builds.builds: print(f" Build ID: {build.id}, Status: {build.status.name}, Create Time: {build.create_time.isoformat()}") except GoogleAPIError as e: print(f"An API error occurred: {e}") print("Please ensure the Cloud Build API is enabled and your credentials have sufficient permissions.") except Exception as e: print(f"An unexpected error occurred: {e}")

Debug

Known issues

gotchaApplication Default Credentials (ADC) is the recommended authentication method. Avoid hardcoding service account key files in your code, especially in production environments. Use `gcloud auth application-default login` for local development or rely on attached service accounts for GCP deployments.

fix

Use `gcloud auth application-default login` for local setup. For GCP deployments (e.g., Cloud Run, GKE, Cloud Functions), ensure your service account has the necessary IAM roles (e.g., Cloud Build Editor or custom roles) and rely on ADC to automatically pick up credentials.

affects: All versions

breakingCloud Build has undergone changes to how it uses service accounts for new projects and the handling of the 'Service Account User' role. This might impact permission configurations, requiring explicit configuration for service account impersonation for managed services.

fix

Review the Cloud Build release notes and official documentation regarding service account changes. Ensure your Cloud Build service account has appropriate permissions and is configured for impersonation if deploying to managed services. For new projects, verify the default service account behavior.

affects: Introduced October 09, 2025 (role removal), July 02, 2024 (new project policy constraints)

gotchaBuild steps in Cloud Build have a default timeout of 10 minutes. Long-running operations may fail with a 'Step exceeded maximum allowed runtime' error if this limit is reached.

fix

For build steps that are expected to take longer, explicitly set the `timeout` field in your `cloudbuild.yaml` for that specific step or for the entire build.

affects: All versions

gotchaThe logging events from `google-cloud-build` (and other Google Cloud Python client libraries) may contain sensitive information, and their occurrence, level, and content can change without being flagged as a breaking change.

fix

Exercise caution when saving or exposing logs. Do not depend on the immutability of logging events for programmatic parsing. Configure log handling explicitly if you need to capture and process logs.

affects: All versions

gotchaThe standard import for the `google-cloud-build` library is `from google.cloud import cloudbuild_v1`. Attempting to import `build_v1` directly from `google.cloud` will result in an `ImportError`.

fix

Ensure the `google-cloud-build` library is installed (`pip install google-cloud-build`) and use the correct import statement: `from google.cloud import cloudbuild_v1`.

affects: All versions

gotchaAn `ImportError` occurs when trying to import `build_v1` from `google.cloud`. This indicates that the `google-cloud-build` package, which provides the Cloud Build API client, is likely not installed in the Python environment, or there's an issue with its installation.

fix

Ensure the `google-cloud-build` library is properly installed in your Python environment (e.g., `pip install google-cloud-build`). Check your project's dependencies (like `requirements.txt`) and your build script or Dockerfile to confirm the package is being installed before execution.

affects: All versions (when `google-cloud-build` is not installed)

Upgrade

Version history

3.37.0latest on PyPI

Audit

Dependencies

google-api-corerequiredCore library for Google API clients, providing common functionality like authentication, retries, and error handling.

google-authrequiredHandles authentication with Google Cloud, including Application Default Credentials.

google-protobufrequiredUsed for serialization and deserialization of API messages.

Agent activity

68 hits · last 30 days

node