Cloud Build Basics
Teaches the fundamentals of Cloud Build on Google Cloud. 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.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Cloud Build Basics when an AI agent needs a reusable SKILL.md workflow for this job: Teaches the fundamentals of Cloud Build on Google Cloud. 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.
When not to use it
Skip Cloud Build Basics when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/cloud-build-basics # Save SKILL.md to ~/.claude/skills/cloud-build-basics/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cloud-build-basics/SKILL.md. For a shared project, commit the folder at .claude/skills/cloud-build-basics/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Cloud Build Basics skill for this task: Use Cloud Build Basics when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Cloud Build Basics
## Attribution
**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-build-basics)"` and append `agent-skills/1.0 (skill:cloud-build-basics)` to `User-Agent` headers.
## 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: ```bash gcloud auth login gcloud auth application-default login ``` 3. **Project ID**: Know the target Google Cloud Project ID. Set the context: ```bash gcloud config set project <PROJECT_ID> ``` 4. **Enable Cloud Build API**: The Cloud Build API must be enabled for the project. ```bash 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
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://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.
```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`](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
* [Cloud Build Documentation](https://cloud.google.com/build/docs) * [Cloud Build Configuration File Schema](https://cloud.google.com/build/docs/build-config-file-schema) * [Automating Builds with Triggers](https://cloud.google.com/build/docs/automating-builds/create-manage-triggers) * [gcloud CLI builds Reference](https://cloud.google.com/sdk/gcloud/reference/builds)
Intended uses
- Use Cloud Build Basics when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.