/cloud-build-basics

name: cloud-build-basics
metadata:
  category: DevOps
description: >-
  Teaches the fundamentals of Google Cloud Build (GCB). Covers core concepts,
  API enablement, console navigation to the Build History page, and the end-to-end
  workflow for creating and manually running a basic build trigger. Do not use for
  managing private pools or complex pipeline architectures.

Google Cloud Build Basics

Prerequisites

Before starting, ensure the following prerequisites are met:

1. **Google Cloud SDK**: Ensure the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) is installed and configured. 2. **Authentication**: Authenticate the gcloud CLI:

    gcloud auth login
    gcloud auth application-default login

3. **Project ID**: Know the target Google Cloud Project ID. Set the context:

    gcloud config set project <PROJECT_ID>

4. **Enable Cloud Build API**: The Cloud Build API must be enabled for the project.

    gcloud services enable cloudbuild.googleapis.com

5. **Permissions**: Ensure the user or service account has the necessary permissions, such as `roles/cloudbuild.builds.editor` and `roles/serviceusage.serviceUsageAdmin` (to enable the API).

Core Concepts

Google Cloud Build (GCB) is a serverless platform that executes your builds on Google Cloud. It translates your source code into deployable artifacts, such as Docker containers or Java archives.

| Concept | Description | | :--- | :--- | | **`cloudbuild.yaml`** | The required configuration file that defines the build steps. It is written in YAML or JSON. | | **Build Steps** | A sequence of actions (steps) GCB performs. Each step runs a command inside a specific Docker container (the builder). Common builders include `gcr.io/cloud-builders/gcloud`, `gcr.io/cloud-builders/docker`, and custom containers. | | **Artifacts** | The output of the build, typically a container image pushed to Google Container Registry (GCR) or Artifact Registry (AR), or other deployable files. | | **Triggers** | Automation rules that invoke a build in response to an event, such as a push to a Git repository, a Pub/Sub message, or a manual request. |

Navigation: Viewing Build History

The Cloud Build Build History page is the central place to monitor the status of past and ongoing builds.

1. **Open the Cloud Console**: Navigate to the Google Cloud Console. 2. **Go to Cloud Build**: Use the search bar or the navigation menu to find **Cloud Build**. 3. **Select Build History**: In the left navigation pane, select **History** (or use the direct URL: `https://console.cloud.google.com/cloud-build/builds`). 4. **Review Builds**:

• **Status**: Check the status column (`SUCCESS`, `FAILURE`, `WORKING`, `QUEUED`).
• **Region**: Use the region filter at the top to view builds that ran in a specific region (important for regional worker pools).
• **Logs**: Click on a specific Build ID to view the detailed logs, execution steps, and build summary. This is crucial for debugging failed builds.

> [!NOTE] > If this is your first time visiting the page, you might see the "zero-state" experience, which offers options to run a sample build or create your first trigger (as noted in the [`cb-list-build-zero-state`](references/cb-list-build-zero-state.md) skill). Note that region settings for triggers and builds are immutable after creation and must be chosen deliberately.

Creating a Basic Automated Trigger

This process defines an automation rule to run a build whenever code is pushed to a specified Git branch.

Step 1: Start Trigger Creation

1. Navigate to the **Cloud Build Triggers** page (`https://console.cloud.google.com/cloud-build/triggers`). 2. Click **Create trigger**.

Step 2: Configure Trigger Settings

1. **Name**: Provide a unique, descriptive name (e.g., `github-main-branch-build`). 2. **Region**: Select the region where the trigger configuration will be stored (e.g., `global` or a specific regional endpoint). **Note: Trigger and build region settings are immutable after creation and must be chosen deliberately.** 3. **Event**: Select the event type. For automated CI/CD, select **Push to a branch**. 4. **Source**: Select the repository source:

• **Repository**: Connect your source repository (GitHub, Bitbucket, Cloud Source Repositories, etc.). If needed, authorize the connection.
• **Repository Name**: Select the specific repository you want to link.

5. **Branch**: Enter the branch pattern (e.g., `^main$` or `^develop`).

Step 3: Configure Build Settings

1. **Configuration**: Select **Cloud Build configuration file (yaml or json)**. 2. **Location**: Keep the default **Repository** and specify the path to your build configuration file (e.g., `cloudbuild.yaml`).

• *Alternative*: For very simple builds, you can choose **Inline** to paste the YAML configuration directly into the trigger.

3. **(Optional) Service Account**: For production environments, select a dedicated service account with limited permissions to enforce the principle of least privilege.

Step 4: Save and Test

1. Click **Create**. The trigger is now active and will run automatically on the next matching Git push.

> [!TIP] > The `cb-create-trigger` skill provides detailed `gcloud` commands for creating triggers across all types (GitHub, Pub/Sub, Webhook) and configurations (inline, Dockerfile, YAML). Use that skill for CLI automation.

Running an Existing Trigger Manually

Sometimes you need to run a trigger on demand, outside of its normal automation flow (e.g., to rebuild an old commit or test a new substitution).

> [!IMPORTANT] > **Substitution Immutability**: You can only override values for substitution variables that are **already defined in the trigger configuration**. You cannot introduce new substitution variable keys at runtime.

Option A: Via the Cloud Console

1. Navigate to the **Cloud Build Triggers** page (`https://c