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

1. Project ID: Know the target Google Cloud Project ID. Set the context:

    gcloud config set project <PROJECT_ID>

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

    gcloud services enable cloudbuild.googleapis.com

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

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

1. (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).

1. 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](references/cb-create-trigger.md): Detailed CLI-focused instructions for creating all trigger types.
• [cb-list-build-zero-state](references/cb-list-build-zero-state.md): Advanced management of the Cloud Build dashboard and onboarding zero state.
• [cb-run-trigger](references/cb-run-trigger.md): 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