Google Cloud Build Basics

Prerequisites

Before starting, ensure the following prerequisites are met:

Google Cloud SDK: Ensure the Google Cloud SDK is installed and configured.

Authentication: Authenticate the gcloud CLI:

bash

gcloud auth login
gcloud auth application-default login

Project ID: Know the target Google Cloud Project ID. Set the context:
bash
```
gcloud config set project <PROJECT_ID>
```
Enable Cloud Build API: The Cloud Build API must be enabled for the project.
bash
```
gcloud services enable cloudbuild.googleapis.com
```
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.

Open the Cloud Console: Navigate to the Google Cloud Console.
Go to Cloud Build: Use the search bar or the navigation menu to find Cloud Build.
Select Build History: In the left navigation pane, select History (or use the direct URL:
```
https://console.cloud.google.com/cloud-build/builds
```
).
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
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

Navigate to the Cloud Build Triggers page (

https://console.cloud.google.com/cloud-build/triggers

Click Create trigger.

Step 2: Configure Trigger Settings

Name: Provide a unique, descriptive name (e.g.,
```
github-main-branch-build
```
).
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.
Event: Select the event type. For automated CI/CD, select Push to a branch.
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.
Branch: Enter the branch pattern (e.g.,
```
^main$
```
or
```
^develop
```
).

Step 3: Configure Build Settings

Configuration: Select Cloud Build configuration file (yaml or json).
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.
(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

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

Navigate to the Cloud Build Triggers page (

https://console.cloud.google.com/cloud-build/triggers

Locate the trigger you wish to run.
Click the vertical ellipsis (⋮) next to the trigger and select Run.
A dialog will appear, allowing you to specify:
- Source branch/tag: Choose the specific Git reference to build from.
- Substitution Variables: Override any existing substitution variables (e.g., set
```
_VERSION
```
  to a new value).
Click Run trigger. The build will start immediately, and you can monitor its status on the History page.

Option B: Via the gcloud CLI

Use the

gcloud builds triggers run

command to invoke the trigger and optionally override parameters.

bash

# Run the trigger against the 'main' branch
gcloud builds triggers run <TRIGGER_NAME> \
    --region=<REGION> \
    --branch=main

# Run the trigger and override a substitution variable
gcloud builds triggers run <TRIGGER_NAME> \
    --region=<REGION> \
    --branch=main \
    --substitutions=_IMAGE_TAG="20231027-manual"

# Monitor the initiated build
# Note: The run command outputs the build ID. Use it to check status:
# gcloud builds log <BUILD_ID> --region=<REGION>

[!NOTE] The
cb-run-trigger
skill provides more complex invocation examples, including running against a specific commit SHA or using tags.

Related Skills

```
cb-create-trigger
```
: Detailed CLI-focused instructions for creating all trigger types.
```
cb-list-build-zero-state
```
: Advanced management of the Cloud Build dashboard and onboarding zero state.
```
cb-run-trigger
```
: Comprehensive guide to manually running triggers using various
```
gcloud
```
options.

cloud-build-basics

NPX Install

Tags

SKILL.md Content