{"id":985,"library":"google-cloud-build","title":"Google Cloud Build","description":"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.","status":"active","version":"3.35.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-build","tags":["google cloud","gcp","build","ci/cd","devops","cloud build"],"install":[{"cmd":"pip install google-cloud-build","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core library for Google API clients, providing common functionality like authentication, retries, and error handling.","package":"google-api-core"},{"reason":"Handles authentication with Google Cloud, including Application Default Credentials.","package":"google-auth"},{"reason":"Used for serialization and deserialization of API messages.","package":"google-protobuf"}],"imports":[{"symbol":"CloudBuildClient","correct":"from google.cloud import build_v1\nclient = build_v1.CloudBuildClient()"}],"quickstart":{"code":"import os\nfrom google.cloud import build_v1\nfrom google.api_core.exceptions import GoogleAPIError\n\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\n\ntry:\n    # Initialize the Cloud Build client\n    client = build_v1.CloudBuildClient()\n\n    # List recent builds for the specified project\n    print(f\"Listing recent builds for project: {project_id}\")\n    request = build_v1.ListBuildsRequest(project_id=project_id)\n    builds = client.list_builds(request=request)\n\n    if not builds.builds:\n        print(\"No builds found.\")\n    else:\n        for build in builds.builds:\n            print(f\"  Build ID: {build.id}, Status: {build.status.name}, Create Time: {build.create_time.isoformat()}\")\n\nexcept GoogleAPIError as e:\n    print(f\"An API error occurred: {e}\")\n    print(\"Please ensure the Cloud Build API is enabled and your credentials have sufficient permissions.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Introduced October 09, 2025 (role removal), July 02, 2024 (new project policy constraints)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (when `google-cloud-build` is not installed)"}],"env_vars":null,"last_verified":"2026-05-12T22:13:30.799Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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.","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.","error":"PERMISSION_DENIED: The caller does not have permission"},{"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.","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.","error":"ModuleNotFoundError: No module named 'google.cloud'"},{"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.","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`.","error":"COPY failed: file not found"},{"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.","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.","error":"ERROR: gcloud crashed (UnicodeDecodeError): 'ascii' codec can't decode byte..."}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.36.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"70.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.8,"import_time_s":null,"mem_mb":null,"disk_size":"68M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"75.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.4,"import_time_s":null,"mem_mb":null,"disk_size":"73M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"66.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.3,"import_time_s":null,"mem_mb":null,"disk_size":"64M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"66.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.3,"import_time_s":null,"mem_mb":null,"disk_size":"64M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"70.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7,"import_time_s":null,"mem_mb":null,"disk_size":"68M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}