Agents CLI 的 CI/CD 与生产发布指南：从 PR 测试到人工审批上线 Google Cloud

Agents CLI 的 CI/CD 与生产发布指南从 PR 测试到人工审批上线 Google Cloud【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本指南围绕 agents-cli 的infra cicd命令完整讲解如何为一键生成的 AI Agent 项目搭建PR 触发测试 → 合并即部署 Staging → 人工审批上生产的三段式 CI/CD 管线。读完你将掌握完整命令与参数、RunnerGitHub Actions / Cloud Build的自动检测逻辑、Terraform 变量体系以及底层流水线文件的作用能够独立把 Agent 项目交付到多环境生产环境。管线如何工作三层环境、三段触发在默认脚手架下agents-cli 生成的 CI/CD 管线遵循环境递进、人工把关的部署模型由三个独立阶段组成与 build_triggers.tf 中定义的三个 Cloud Build Trigger 一一对应CI 管线Pull Request 触发当开发者向main分支提交 Pull Request 时自动执行单元测试与集成测试对应 triggerpr-project_namepull_request事件 filename .cloudbuild/pr_checks.yaml。该 trigger 默认只监控agent 目录/**、tests/**、deployment/**与uv.lock的变化避免无关文件改动白白消耗构建时间。Staging CD 管线merge 到main触发PR 合并后triggercd-project_namepush事件 filename .cloudbuild/staging.yaml开始执行构建容器镜像并推送到Artifact Registry部署到staging 环境运行自动化负载测试默认使用 locust 以-t 30s -u 10的参数压测详见 staging.yaml负载测试结果CSV HTML 报告上传到 staging 项目的日志 GCS 桶一切通过后自动触发生产部署 trigger。生产部署staging 成功后触发需人工审批triggerdeploy-project_name使用approval_config { approval_required true }强制开启人工审批只有审批通过后才会在deploy-to-prod.yaml中执行生产部署。关键设计是生产环境部署的镜像是 staging 已验证过的同一个镜像构建步骤中两者都使用$_REGION-docker.pkg.dev/$PROJECT_ID/$_ARTIFACT_REGISTRY_REPO_NAME/$_CONTAINER_NAME:$SHORT_SHA从而保证生产跑的就是测试过的东西。一条命令搭建全套管线在项目根目录执行一条命令即可完成基础设施预置与 CI/CD 配置agents-cli infra cicd \ --staging-project my-staging-project \ --prod-project my-prod-project该命令会自动完成三件事基础设施预置通过 Terraform 为 staging 与 production 分别创建项目级资源CI/CD 配置按你选择的 RunnerCloud Build 或 GitHub Actions生成触发器和流水线仓库连接连接或创建GitHub 仓库并配置 remote。从源码看setup_cicdcmd_cicd.py在非交互模式下要求--staging-project、--prod-project、--repository-name必须显式给出--repository-owner未提供时会通过gh api user自动取当前 GitHub 用户任何缺失都会抛出UsageError并提示用-i / --interactive进入交互模式逐项填写。交互模式还会引导完成 GitHub CLI 认证、Cloud Build GitHub 连接创建等前置步骤。完整参数表Flag说明备注--staging-projectGCP 项目 IDstaging用于运行测试与负载压测必填--prod-projectGCP 项目 IDproduction必填--cicd-project单独存放 CI/CD 资源的 GCP 项目不传时默认复用 prod 项目--dev-projectDev 项目可选提供后会额外执行deployment/terraform/single-project的 Terraform--regionGCP 区域自动从deployment/terraform/cicd/vars/env.tfvars检测检测不到时使用默认值us-east1--repository-nameGitHub 仓库名非交互模式下必填--repository-ownerGitHub 仓库属主用户名或组织缺省自动取当前 GitHub 用户--host-connection-nameCloud Build 主机连接名缺省为git-repository-name--github-patGitHub Personal Access Token支持环境变量GH_TOKEN/GITHUB_TOKENCloud Build 编程模式必填--github-app-installation-idGitHub App 安装 IDCloud Build 编程模式必填--cicd-runner选择 Runnergoogle_cloud_build或github_actions不传则自动检测--create创建新的 GitHub 仓库不加此参数则使用已存在的仓库--local-state使用本地 Terraform state缺省使用 GCS 远端 state--apply实际应用 Terraform 变更不加则只执行terraform plan预览--force-bucket--force允许使用属于其他 GCP 项目的 state 桶默认禁止用于防止桶抢占攻击-i / --interactive交互模式引导填写缺失参数--debug开启调试日志—值得注意的两点实现细节默认只做 plan命令默认以terraform plan结尾并提示要应用变更请加--apply。但 plan 模式下仍会写入env.tfvars、Terraform 模板并验证 GitHub 认证、Cloud Build 连接等云端前置条件——因为这些是生成准确 plan 的前提远端 state 使用 GCS非--local-state时命令会在 CI/CD 项目中创建gs://cicd-project-terraform-state桶启用版本控制并在deployment/terraform/cicd与deployment/terraform/single-project两个目录分别写入backend.tfstate 前缀分别为repository_name/prod与repository_name/dev让两套基础设施的 state 相互隔离。CI/CD Runner 检测机制agents-cli infra cicd不要求你手动指定 Runner它会从项目中的 Terraform 配置自动识别Runner检测方式认证方式GitHub Actions检测到deployment/terraform/cicd/下同时存在wif.tf与github.tf使用 Workload Identity FederationWIF实现 keyless 认证无需长期凭据Google Cloud Build未检测到 WIF 配置时回退为该 Runner创建 Cloud Build 到 GitHub 的托管连接检测逻辑在源码中非常直接cmd_cicd.pyis_github_actions (tf_dir / wif.tf).exists() and (tf_dir / github.tf).exists() cicd_runner github_actions if is_github_actions else google_cloud_buildGitHub ActionsWIF 无密钥认证选择 GitHub Actions 时wif.tf 会创建 Workload Identity Pool 与 OIDC Providerissuer 为 GitHub 的 token 端点并通过attribute_condition attribute.repository owner/repo把信任范围精确锁定到你的仓库。随后 github.tf 自动把以下变量/密钥写进仓库的 Actions Secrets供工作流直接引用WIF_POOL_ID、WIF_PROVIDER_ID、GCP_SERVICE_ACCOUNT用于google-github-actions/auth换取短期凭证STAGING_PROJECT_ID、PROD_PROJECT_ID、CICD_PROJECT_ID、REGIONAPP_SA_EMAIL_STAGING/APP_SA_EMAIL_PROD、LOGS_BUCKET_NAME_STAGING/LOGS_BUCKET_NAME_PRODCloud Run / GKE 部署目标专属的CONTAINER_NAME、ARTIFACT_REGISTRY_REPO_NAME、GKE_CLUSTER_NAME_*同时会创建production这个 GitHub 环境并开启部署分支策略让生产部署与审批绑定到环境维度。Cloud Build托管连接 Secret Manager选择 Cloud Build 时命令通过 gcloud CLI 创建github类型的托管连接连接名默认git-repository-name并把 GitHub PAT 存入 Secret Managersecret id 默认github-pat随后由 Terraform 中的 github.tf 引用该 secret 并创建google_cloudbuildv2_connection与google_cloudbuildv2_repository资源。GitHub CLI 前置要求无论哪种 Runner命令都会校验 GitHub CLIgh未安装时直接中止并提示安装未认证时会引导完成gh auth login交互模式支持浏览器或 token 两种方式认证后还会按 Runner 校验 token scopesgithub_actions需要repo和workflowgoogle_cloud_build至少需要repo缺失时提示gh auth login --scopes repo,workflow。流水线文件三个 Cloud Build YAML 干了什么Terraform trigger 只负责何时触发真正的执行逻辑在.cloudbuild/*.yaml中Python 模板见 base_templates/python/.cloudbuildGo / Java / TypeScript 模板同构pr_checks.yaml先安装uv并uv sync --locked锁定依赖然后uv run pytest tests/unit与uv run pytest tests/integration依次运行单元测试和集成测试options 中注入GOOGLE_GENAI_USE_VERTEXAItrue等环境变量以支持 Agent 进程内集成测试。staging.yaml按部署目标分支执行——Cloud Run 用 docker build/push 后调用google-agents-cli deploy --project ${_STAGING_PROJECT_ID}GKE 额外带--cluster-nameAgent Runtime 则uv sync --locked后直部署。随后抓取 staging 服务 URL 与 ID Token用uvx locust2.31.1跑负载测试把结果上传到 staging 日志桶最后gcloud beta builds triggers run deploy-project_name --sha $COMMIT_SHA触发生产部署。deploy-to-prod.yaml使用同一个镜像 tag 部署到${_PROD_PROJECT_ID}并在OTEL_RESOURCE_ATTRIBUTES中写入service.version$COMMIT_SHA用于观测追踪GKE 目标使用${var.project_name}-prod集群见 build_triggers.tf 中的 substitutions。Terraform 变量体系管线全部由deployment/terraform/cicd/目录下的 Terraform 配置驱动模板源码位于 base_templates/_shared/deployment/terraform/cicd。setup_cicd会把项目 ID、region、仓库信息等写入vars/env.tfvars随后执行terraform initplan/applyrun_terraform的实现见 _cicd_utils.py统一使用-inputfalse缺失变量会直接报错而非阻塞等待输入。核心变量定义在 variables.tf变量说明默认值project_name资源命名的基名trigger 名、池名、集群名等均以此为前缀脚手架项目名prod_project_id生产 GCP 项目 ID无必填staging_project_idStaging GCP 项目 ID无必填cicd_runner_project_idCI/CD 管线执行所在的 GCP 项目 ID无必填region资源部署区域us-east1注意命令默认值同样为us-east1repository_name连接到 CI/CD 的 GitHub 仓库名无必填repository_owner仓库属主用户名或组织无必填host_connection_nameCloud Build 主机连接名project-github-connectionapp_sa_roles应用服务账号的角色列表aiplatform.user、logging.logWriter、cloudtrace.agent、storage.admin、serviceusage.serviceUsageConsumer等按会话类型追加cloudsql/bigquery角色cicd_rolesCI/CD Runner 服务账号在 CI/CD 项目中的角色storage.admin、aiplatform.user、logging.logWriter、cloudtrace.agent、artifactregistry.writer、cloudbuild.builds.builder及部署目标专属角色cicd_sa_deployment_required_rolesRunner 服务账号在 Staging / Prod 项目中的部署角色iam.serviceAccountUser、aiplatform.user、storage.admin及部署目标专属角色create_repository是否新建 GitHub 仓库falsegithub_app_installation_id/github_pat_secret_id/create_cb_connectionCloud Build 专属App 安装 ID、PAT secret 引用、连接是否已由 gcloud 创建null/null/false提示原文档表格中 region 默认值写为us-west1但当前仓库的实际默认值是us-east1见 variables.tf 与 cmd_cicd.py 中的region us-east1实践时请以仓库实际配置为准。安全性设计状态桶防桶抢占远端 Terraform state 集中存放在 GCS 桶若被恶意占用可能造成严重风险。ensure_bucket_exists_cicd_utils.py对此做了三重状态校验桶不存在 → 在 CI/CD 项目中创建并开启版本控制桶存在且属于当前项目 → 直接复用桶存在但属于其他 GCP 项目→ 默认抛出Security Error提示可能存在 bucket squatting 攻击只有显式传入--force-bucket才继续。此外 Terraform 运行也内置了指数退避重试backoff默认 factor 2.0、最长 60 秒提升云 API 偶发失败的容错性。部署完成后的下一步基础设施与管线就绪后把代码推送到 GitHub 仓库PR 与 merge 会自动驱动 CI/CD。对于部署在 Agent Runtime 的服务可进一步将其注册到 Gemini Enterpriseagents-cli publish gemini-enterprisepublish命令组中gemini-enterprise子命令用于把 Agent Runtime 注册为 Gemini Enterprise 上的服务见 cmd_publish_group.py支持--gemini-enterprise-app-id等参数具体选项可运行agents-cli publish gemini-enterprise --help常见问题与排障要点Terraform 配置缺失若项目以 prototype 模式创建deployment/terraform/cicd/下可能没有variables.tf命令会直接报错并提示先运行agents-cli scaffold enhance补全部署配置见 cmd_cicd.py 的检查逻辑仓库状态校验--create与已存在仓库、或未加--create但仓库不存在都会在早期被gh repo view拦截并给出明确的修正提示编程模式与交互模式自动化场景如 CI 中用--staging-project、--prod-project、--repository-name加--github-pat、--github-app-installation-id日常人工使用建议-i交互模式由命令逐步引导完成认证与连接创建审批入口生产部署触发后审批操作在 Cloud Build Console 中完成staging 流水线末尾会打印控制台链接与提示GitHub Actions 场景则通过production环境的审批策略控制。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考