Back to Details

cloud-build-basics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Cloud Build Basics

Google Cloud Build 基础

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:
    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).
开始之前，请确保满足以下前提条件：
  1. Google Cloud SDK：确保已安装并配置Google Cloud SDK。
  2. 身份验证：对gcloud CLI进行身份验证：
    bash
    gcloud auth login
gcloud auth application-default login
  3. 项目ID：了解目标Google Cloud项目ID，并设置上下文：
    bash
    gcloud config set project <PROJECT_ID>
  4. 启用Cloud Build API：项目必须启用Cloud Build API。
    bash
    gcloud services enable cloudbuild.googleapis.com
  5. 权限：确保用户或服务账号拥有必要权限，例如
    roles/cloudbuild.builds.editor
    和
    roles/serviceusage.serviceUsageAdmin
    （用于启用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.
ConceptDescription
cloudbuild.yaml
The required configuration file that defines the build steps. It is written in YAML or JSON.
Build StepsA 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.
ArtifactsThe output of the build, typically a container image pushed to Google Container Registry (GCR) or Artifact Registry (AR), or other deployable files.
TriggersAutomation 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.
Google Cloud Build（GCB）是一个无服务器平台，可在Google Cloud上执行构建任务。它将源代码转换为可部署工件，例如Docker容器或Java归档文件。
概念说明
cloudbuild.yaml
必填的配置文件，用于定义构建步骤，采用YAML或JSON格式编写。
构建步骤GCB执行的一系列操作（步骤）。每个步骤在特定Docker容器（构建器）内运行命令。常见构建器包括
gcr.io/cloud-builders/gcloud
、
gcr.io/cloud-builders/docker
以及自定义容器。
工件构建的输出，通常是推送到Google Container Registry（GCR）或Artifact Registry（AR）的容器镜像，或其他可部署文件。
触发器响应事件（如Git仓库推送、Pub/Sub消息或手动请求）而触发构建的自动化规则。

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.
Cloud Build构建历史页面是监控过往和正在进行的构建状态的中心位置。
  1. 打开Cloud控制台：导航至Google Cloud控制台。
  2. 进入Cloud Build：使用搜索栏或导航菜单找到Cloud Build。
  3. 选择构建历史：在左侧导航窗格中选择History（或使用直接URL：
    https://console.cloud.google.com/cloud-build/builds
    ）。
  4. 查看构建信息：
    • 状态：查看状态列（
      SUCCESS
      、
      FAILURE
      、
      WORKING
      、
      QUEUED
      ）。
    • 区域：使用顶部的区域过滤器查看在特定区域运行的构建（这对区域工作池很重要）。
    • 日志：点击特定的构建ID查看详细日志、执行步骤和构建摘要。这对调试失败的构建至关重要。
[!NOTE] 如果是首次访问该页面，你可能会看到“零状态”界面，它提供了运行示例构建或创建第一个触发器的选项（如
cb-list-build-zero-state
技能中所述）。请注意，触发器和构建的区域设置在创建后不可更改，必须谨慎选择。

Creating a Basic Automated Trigger

创建基础自动化触发器

This process defines an automation rule to run a build whenever code is pushed to a specified Git branch.
此流程定义了一个自动化规则，每当代码推送到指定Git分支时就运行构建。

Step 1: Start Trigger Creation

步骤1：开始创建触发器

  1. Navigate to the Cloud Build Triggers page (
    https://console.cloud.google.com/cloud-build/triggers
    ).
  2. Click Create trigger.
  1. 导航至Cloud Build触发器页面（
    https://console.cloud.google.com/cloud-build/triggers
    ）。
  2. 点击创建触发器。

Step 2: Configure Trigger Settings

步骤2：配置触发器设置

  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
    ).
  1. 名称：提供唯一且描述性的名称（例如
    github-main-branch-build
    ）。
  2. 区域：选择存储触发器配置的区域（例如
    global
    或特定区域端点）。注意：触发器和构建的区域设置在创建后不可更改，必须谨慎选择。
  3. 事件：选择事件类型。对于自动化CI/CD，选择推送到分支。
  4. 源：选择仓库源：
    • 仓库：连接你的源代码仓库（GitHub、Bitbucket、Cloud Source Repositories等）。如有需要，授权连接。
    • 仓库名称：选择要链接的特定仓库。
  5. 分支：输入分支模式（例如
    ^main$
    或
    ^develop
    ）。

Step 3: Configure Build Settings

步骤3：配置构建设置

  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.
  1. 配置：选择Cloud Build配置文件（yaml或json）。
  2. 位置：保留默认的仓库，并指定构建配置文件的路径（例如
    cloudbuild.yaml
    ）。
    • 替代方案：对于非常简单的构建，你可以选择内联，直接将YAML配置粘贴到触发器中。
  3. （可选）服务账号：对于生产环境，选择具有有限权限的专用服务账号，以遵循最小权限原则。

Step 4: Save and Test

步骤4：保存并测试

  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.
  1. 点击创建。触发器现在已激活，下次匹配Git推送时将自动运行。
[!TIP] 
cb-create-trigger
技能提供了详细的
gcloud
命令，用于创建所有类型的触发器（GitHub、Pub/Sub、Webhook）和配置（内联、Dockerfile、YAML）。如需CLI自动化，请使用该技能。

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.
有时你需要按需运行触发器，而不遵循其正常自动化流程（例如，重新构建旧提交或测试新的替换变量）。
[!IMPORTANT] 替换变量不可变性：你只能覆盖已在触发器配置中定义的替换变量的值。无法在运行时引入新的替换变量键。

Option A: Via the Cloud Console

选项A：通过Cloud控制台

  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.
  1. 导航至Cloud Build触发器页面（
    https://console.cloud.google.com/cloud-build/triggers
    ）。
  2. 找到你要运行的触发器。
  3. 点击触发器旁边的垂直省略号（⋮），选择运行。
  4. 将弹出一个对话框，允许你指定：
    • 源分支/标签：选择要构建的特定Git引用。
    • 替换变量：覆盖任何现有替换变量（例如，将
      _VERSION
      设置为新值）。
  5. 点击运行触发器。构建将立即启动，你可以在历史页面监控其状态。

Option B: Via the gcloud CLI

选项B：通过gcloud CLI

Use the 
gcloud builds triggers run
command to invoke the trigger and optionally override parameters.
bash
undefined
使用
gcloud builds triggers run
命令调用触发器，并可选择覆盖参数。
bash
undefined

Run the trigger against the 'main' branch

针对'main'分支运行触发器

gcloud builds triggers run <TRIGGER_NAME>
--region=<REGION>
--branch=main
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"
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:

注意：run命令会输出构建ID。使用它检查状态：

gcloud builds log <BUILD_ID> --region=<REGION>

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.

> [!NOTE]
> `cb-run-trigger`技能提供了更复杂的调用示例，包括针对特定提交SHA或使用标签运行。

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.
  • cb-create-trigger
    ：针对创建所有触发器类型的详细CLI导向说明。
  • cb-list-build-zero-state
    ：Cloud Build仪表板的高级管理和零状态入门。
  • cb-run-trigger
    ：使用各种
    gcloud
    选项手动运行触发器的综合指南。

External Resources & Documentation

外部资源与文档