Cloud Build 零状态初始化实战：从样本构建到触发器创建的完整 gcloud 工作流（Google Agent Skills 之 cloud-build-basics）

Cloud Build 零状态初始化实战从样本构建到触发器创建的完整 gcloud 工作流Google Agent Skills 之 cloud-build-basics【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文基于 Google 官方 Agent Skills 仓库中cloud-build-basics技能的参考文档 cb-list-build-zero-state.md 展开系统讲解 Google Cloud BuildGCB零状态zero-state项目的首次初始化工作流如何验证项目尚无任何构建记录、运行官方样本构建、创建 GitHub 触发器、使用内联配置以及处理区域不可变与司法管辖DRZ/BYOID环境带来的限制。读完本文你可以直接复制文中的gcloud命令完成从零开始的首次构建并为 Agent 驱动的云构建自动化提供一套可验证、可复现的操作清单。技能定位什么是 Cloud Build 的零状态体验Cloud Build 是一个无服务器构建平台负责把源代码编译成 Docker 容器、Java 归档等可部署产物支持手动提交构建、通过触发器Trigger在 Git 推送等事件发生时自动构建。当用户第一次打开 Cloud Build 控制台时如果项目中没有任何构建历史或触发器控制台会展示一个零状态引导界面提供运行样本构建Run sample build和创建第一个触发器等入口。本技能文档 cb-list-build-zero-state.md 正是为这一场景而设计它管理 Cloud Build 的零状态体验涵盖运行样本构建、创建触发器以及处理区域Region或司法管辖jurisdictional如 DRZ 环境带来的限制。该文档位于父技能 cloud-build-basics/SKILL.md 的references/目录下父技能负责核心概念、API 启用与控制台导航等基础教学而本文对应的参考文档则专注于从零到第一次成功构建的可执行工作流。两者在父技能中通过一条 NOTE 相互呼应首次访问构建历史页时会看到零状态体验且触发器与构建的区域设置在创建后不可更改必须在初始化时审慎选择。从仓库结构看references/目录下的三份文档构成一个完整的技能族cb-list-build-zero-state.md本文主体零状态验证与首建工作流cb-create-trigger.md覆盖全部触发器类型GitHub、Pub/Sub、Webhook、Manual与全部配置形式仓库 YAML/JSON、Dockerfile、Buildpacks、内联 YAML的详细创建指南cb-run-trigger.md手动执行已有触发器的指南支持按分支、标签或 commit SHA 指定源码版本并覆盖替换变量。前置条件认证、API 与权限清单执行零状态工作流前需要满足以下四项前置条件完整继承自文档 Preconditions 一节1. 认证Authenticationgcloud auth login gcloud auth application-default login第一条命令完成交互式登录第二条为后续可能用到 SDK/REST 的调用建立应用默认凭证Application Default Credentials。2. 项目 IDProject ID文档明确指示若目标 GCP 项目的projectId未知应向用户主动询问而不是猜测。项目 ID 是后续所有命令的上下文锚点。3. 启用 APIEnabled APIs确保 Cloud Build API 已在项目中启用cloudbuild.googleapis.com父技能 SKILL.md 给出了对应的启用命令gcloud services enable cloudbuild.googleapis.com并且提示启用 API 的用户或服务账号需要roles/serviceusage.serviceUsageAdmin权限。4. IAM 权限Permissions执行该工作流需要以下细粒度权限权限说明cloudbuild.builds.list列出构建Step 2 零状态验证依赖此权限cloudbuild.builds.get查看单个构建详情cloudbuild.builds.create创建/提交构建roles/cloudbuild.builds.editor推荐直接授予此预定义角色覆盖以上细粒度权限输入参数八个可配置项及其默认值文档以表格形式定义了该工作流的全部输入参数完整继承如下名称类型说明必填/可选默认值projectIdStringGCP 项目 ID必填-regionString构建/触发器的区域位置如us-central1。注意触发器创建后区域不可更改可选globaltriggerNameString新构建触发器的名称可选-repoOwnerStringGitHub/Bitbucket 仓库的 Owner如GoogleCloudBuild可选-repoNameString仓库名称如cloud-console-sample-build可选-branchPatternString触发构建的分支正则如^main$可选^main$substitutionsMap构建替换变量键值对如_KEYVALUE可选-serviceAccountString执行构建的服务账号邮箱可选默认 GCB 服务账号结合姊妹文档 cb-create-trigger.md 的输入定义可以补充两点实操细节region在触发器创建场景下是必填项默认global且 2 代仓库连接2nd_gen在global区域不可用require_approval参数控制构建是否需要人工审批默认false——本文 Step 4 示例命令中的--require-approval标志正是将其置为开启适合生产分支的首次接入。文档还给出了一条关键的区域约束提示样本构建不支持司法管辖DRZ或 BYOID 环境。1 代仓库连接在 DRZ 区域US、EU、Saudi Arabia被禁用。这意味着在受数据驻留/主权限制的项目中Option A样本构建不可用只能选择基于 2 代仓库连接的触发器路径。该约束在 cb-run-trigger.md 中也有呼应DRZ 环境下使用传统 1 代仓库的触发器无法手动运行仅支持 2 代仓库。执行流程七步完成零状态初始化Step 1认证与项目选择为后续所有命令设置项目上下文gcloud auth login gcloud auth application-default login gcloud config set project PROJECT_IDgcloud config set project将当前 CLI 会话绑定到目标项目后续gcloud builds ...命令都会作用于该项目。Step 2验证项目的零状态确认目标区域中当前不存在任何构建或触发器# 列出最近的构建以验证空状态 gcloud builds list --regionREGION --limit5 # 列出现有触发器 gcloud builds triggers list --regionREGION验证标准如果项目确实处于零状态上述两条命令应返回无结果或空列表。这一步的意义在于零状态初始化不仅是跑通第一次构建更是团队确立区域策略的窗口期——触发器和构建的区域设置在创建后不可变Region Immutability必须在初始化阶段审慎决定。若此处跳过验证可能把已有触发器项目的区域习惯沿用下来而新资源却无法与之对齐。Step 3Option A运行样本构建手动使用官方示例代码快速体验 Cloud Build等价于控制台中的Run sample build CTA# 克隆示例仓库 git clone https://github.com/GoogleCloudBuild/cloud-console-sample-build \ cd cloud-console-sample-build # 向 Cloud Build 提交构建 gcloud builds submit --config cloudbuild.yaml --regionREGION该示例仓库的 Owner 为GoogleCloudBuild、仓库名为cloud-console-sample-build与输入参数表中repoOwner/repoName的默认示例值一致。gcloud builds submit会从本地目录读取cloudbuild.yaml并发起构建返回构建 ID。注意 Option A 的前提是项目位于支持样本构建的常规非 DRZ/BYOID环境。Step 4Option B创建触发器持续部署创建一个在代码变更时自动启动构建的触发器gcloud builds triggers create github \ --nameTRIGGER_NAME \ --repo-nameREPO_NAME \ --repo-ownerREPO_OWNER \ --branch-patternBRANCH_PATTERN \ --build-configcloudbuild.yaml \ --regionREGION \ --require-approval参数要点--branch-pattern为正则表达式默认示例为^main$仅主分支--build-config指向仓库内的构建配置文件路径此处为根目录的cloudbuild.yaml--require-approval使每次触发的构建在执行前需要人工审批适合在首次接入 CI 时为生产分支加一道安全闸。如需覆盖全部触发器类型Manual、Webhook、Pub/Sub以及 Buildpacks/Dockerfile/内联配置等形式参见 cb-create-trigger.md——该文档列出了push_branch、push_tag、pull_request、manual、pubsub、webhook六种事件类型及github、cloud_source_repositories、bitbucket、gitlab、developer_connect五类仓库服务并提示组织策略如constraints/cloudbuild.allowedServiceAccounts、constraints/gcp.resourceLocations可能限制服务账号选择与区域可用性。Step 5Option C内联配置触发器当仓库内没有现成的cloudbuild.yaml或希望构建步骤与仓库解耦时可用内联构建配置创建触发器gcloud builds triggers create github \ --nameTRIGGER_NAME \ --repo-nameREPO_NAME \ --repo-ownerREPO_OWNER \ --branch-patternBRANCH_PATTERN \ --inline-configlocal-config.yaml \ --regionREGION--inline-config指向本地的 YAML 文件其内容会被完整嵌入触发器资源中。父技能 SKILL.md 指出对于非常简单的构建控制台也提供 Inline 选项允许直接把 YAML 粘贴进触发器——两条路径在资源层面是等价的。Step 6高级设置与约束针对安全、网络或身份需求进行精细化配置。身份与替换变量为触发器指定专用服务账号并更新替换变量# 更新触发器指定服务账号与替换变量 gcloud builds triggers update github TRIGGER_NAME \ --service-accountprojects/PROJECT_ID/serviceAccounts/SA_EMAIL \ --update-substitutions_VERSIONv1,_ENVprod \ --regionREGION服务账号使用完整的资源路径格式projects/PROJECT_ID/serviceAccounts/SA_EMAILcb-create-trigger.md 强调为触发器使用用户管理的服务账号时操作者还需具备roles/iam.serviceAccountUser即iam.serviceAccounts.actAs权限。处理区域不可达Regional Outages若某区域不可达例如us-east4出现警告仍可从其他位置列出构建以确认服务整体可用# 检查不可达位置的状态 gcloud builds list --regionglobalStep 7监控构建执行在触发或提交构建后跟踪其进度# 按样本标签列出构建 gcloud builds list --filtertagsgcp-cloud-build-sample-build --regionREGION # 查看指定构建的日志 gcloud builds log BUILD_ID --regionREGIONgcloud builds submit会输出构建 IDbuildId随后即可用它流式查看日志。父技能 SKILL.md 在查看构建历史一节中还说明了控制台侧的对应操作在 Build History 页面按 Status 列SUCCESS、FAILURE、WORKING、QUEUED和区域过滤器排查构建点击 Build ID 查看详细日志与执行步骤——这对于调试失败构建尤为关键。姊妹文档 cb-run-trigger.md 则补充了手动执行触发器的三种源码定位方式--branch、--tag、--sha与替换变量覆盖--substitutions_IMAGE_TAG20231027-manual并提醒替换变量覆盖有一个重要限制只能覆盖触发器配置中已定义的替换键运行时不能引入新的键名。输出工作流交付的四个结果字段文档定义了该工作流的输出契约名称类型说明buildIdString所执行构建的唯一标识符triggerIdString所创建触发器的唯一标识符statusString构建的最终状态如SUCCESS、FAILUREimageUriString所构建容器镜像的 URI如适用其中buildId是串联后续所有观测动作的主键gcloud builds log BUILD_ID、gcloud builds describe BUILD_ID以及控制台日志链接都依赖它。若构建配置中包含images:字段如推送到 Artifact RegistryimageUri即指向最终产物镜像。适用边界与技能协作该文档及其父技能明确划定了适用边界SKILL.md 声明cloud-build-basics不适用于管理私有构建池private pools或复杂流水线架构cb-list-build-zero-state.md 的 Related skills 一节则列出三个协作技能cb-connect-repo仓库连接、cb-run-trigger手动运行触发器、artifact-registry-manage-images镜像管理其中前两者的完整文档已随仓库提供可直接查阅。需要特别说明的适用前提文中命令以 Google Cloud SDKgcloud CLI已安装并可用为前提区域参数在触发器场景中必须显式确定创建后不可变更在 DRZ/BYOID 环境中应放弃 Option A 样本构建路径改用 2 代仓库连接。按上述约束执行即可完成一个 Cloud Build 项目从空状态到首次成功构建、并接入持续触发式构建的完整初始化。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考