cloud-build-basics

Google Cloud Build Basics

Prerequisites

Before starting, ensure the following prerequisites are met:

1. Google Cloud SDK: Ensure the Google Cloud SDK 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 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://console.cloud.google.com/cloud-build/triggers).
2. Locate the trigger you wish to run.
3. Click the vertical ellipsis (⋮) next to the trigger and select Run.
4. 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).
5. 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.

# 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.

External Resources & Documentation

• Google Cloud Build Documentation
• Cloud Build Configuration File Schema
• Automating Builds with Triggers
• gcloud CLI builds Reference