Google Cloud Build
raw JSON → 3.35.0 verified Tue May 12 auth: no python install: stale
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.
pip install google-cloud-build Common errors
error PERMISSION_DENIED: The caller does not have permission ↓
cause The Cloud Build service account (or the user running a manual build) lacks the necessary IAM permissions for the resources it's trying to access or manipulate, such as Cloud Storage for logs, Artifact Registry for pushing images, or Cloud Run for deployment.
fix
Grant the appropriate IAM roles to the Cloud Build service account (e.g.,
roles/cloudbuild.editor, roles/artifactregistry.writer, roles/run.developer). For manual builds, ensure the user has Project Viewer and Cloud Build Editor roles. error ModuleNotFoundError: No module named 'google.cloud' ↓
cause The Python environment within the Cloud Build step or Docker image does not have the required `google-cloud` library (or other specified modules) installed or correctly configured in its `PYTHONPATH`. This often happens when `pip install` commands are not correctly executed or virtual environments are not activated across build steps.
fix
Ensure
pip install google-cloud-build (or other necessary packages like google-cloud-vision, etc.) is executed in a build step before the module is imported. For Dockerfiles, make sure dependencies are installed within the image build process and that the Python path is correctly set. error COPY failed: file not found ↓
cause A `COPY` instruction in the `Dockerfile` used by Cloud Build is attempting to copy a file or directory that does not exist in the build context or at the specified relative path. This can be due to an incorrect working directory or files being excluded by `.gcloudignore` or `.dockerignore`.
fix
Verify that the file paths specified in the
Dockerfile are correct relative to the build context. Check for and adjust .gcloudignore or .dockerignore files if they are inadvertently excluding necessary files. error ERROR: gcloud crashed (UnicodeDecodeError): 'ascii' codec can't decode byte... ↓
cause A `gcloud` command executed within a Cloud Build step encounters a character encoding issue, typically when non-ASCII characters are present in configuration files like `app.yaml` or in file paths within the project.
fix
Identify and remove any non-ASCII characters from
app.yaml and other relevant configuration files or file paths within your project. Ensure all text files are saved with UTF-8 encoding. Warnings
gotcha Application 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.
breaking Cloud 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.
gotcha Build 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.
gotcha The 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.
gotcha The 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`.
gotcha An `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.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - - 70.3M
3.10 alpine (musl) - - - -
3.10 slim (glibc) wheel 5.8s - 68M
3.10 slim (glibc) - - - -
3.11 alpine (musl) wheel - - 75.1M
3.11 alpine (musl) - - - -
3.11 slim (glibc) wheel 5.4s - 73M
3.11 slim (glibc) - - - -
3.12 alpine (musl) wheel - - 66.5M
3.12 alpine (musl) - - - -
3.12 slim (glibc) wheel 4.3s - 64M
3.12 slim (glibc) - - - -
3.13 alpine (musl) wheel - - 66.2M
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 4.3s - 64M
3.13 slim (glibc) - - - -
3.9 alpine (musl) wheel - - 70.4M
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 7.0s - 68M
3.9 slim (glibc) - - - -
Imports
- CloudBuildClient
from google.cloud import build_v1 client = build_v1.CloudBuildClient()
Quickstart last tested: 2026-04-24
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}")