besimple-oss/broccoli 源码：https://github.com/besimple-oss/broccoli # 🥦 Broccoli OSS 你的工程循环 AI 队友。

Broccoli 把 Linear 工单变成已合并的 PR——由 Claude 与 Codex 驱动，跑在你自己的 Google Cloud 上。
CI (https://github.com/besimple-oss/broccoli/actions/workflows/ci.yml) License: MIT Python 3.12+ (https://www.python.org/downloads/) 运行在 Cloud Run (https://cloud.google.com/run) — ## 为什么选 Broccoli - 🎯 Linear 工单 → 可review 的 PR。 把 issue 指派给 Broccoli 机器人，睡一觉就能看到它规划、实现并发起 PR。 - 🔒 你的 infra、你的 key、你的数据。 部署到你的 GCP 项目、连你的 Postgres。无第三方控制面，数据不出境。 - 🧱 上线即生产级。 Serverless Cloud Run + Secret Manager + webhook 去重 + 持久化任务状态，不是玩具。 - 🧩 提示词归你。 先拿我们自带的模板，fork、调优、随代码版本管理。 - ⚡ 每份 PR 都有 AI code review。 Claude 与 Codex 读 diff、留可执行评论、你点头就自动补 commit。 - 🛠️ 约 30 分钟部署完。 一条 bootstrap 脚本、一个配置文件、两条 webhook，开船。 ## 配合 Coding Agent 使用 把下面整段提示词丢给你喜欢的 coding agent（我们用 codex cli）。

将此仓库部署到我的 Google Cloud 项目。  
若只给了 GitHub 地址，先 clone；若已本地打开，直接用现有代码。  
按仓库里的部署说明、脚本及 `.agents/skills/broccoli-oss-gcp-deploy/SKILL.md` 执行。  
视为“部署”请求，而非仅浏览代码。  
不要假设我已完成任何前置条件。  
开始“发现”前，逐个确认以下检查点，每步等我答复再继续。若 README 里已有对应章节，直接指给我看，不再复述。  

1. GCP 项目 + 计费。  
   询问我是否已有启用了计费的 Google Cloud 项目，且 `gcloud` 已登录该账号。  
   若无，引导我在 https://console.cloud.google.com/cloud-resource-manager 创建项目并在 https://console.cloud.google.com/billing/projects 绑定计费，或让部署技能代建。记录 Project ID。  

2. GitHub App。  
   问是否已给 Broccoli 创建 GitHub App 并授予所需权限（Contents、Pull requests、Issues = 读写；Metadata = 只读；订阅 `Pull request review` 事件）。  
   若无，逐步带我完成 `README.md -> Deploy it on your GCP -> 1. Create a GitHub App`。  
   让我记录数字 App ID 并下载私钥 PEM 文件到本地。Homepage/Webhook URL 可先用占位符，bootstrap 会打印真实地址。  

3. Linear 机器人用户 + API key。  
   重要：Linear API key 必须来自**专用机器人用户**，而非我个人账号，否则“指派给机器人即触发”流程会静默失败。  
   问是否已有专用机器人用户。  
   若无，带我完成 `README.md -> 2. Designate a Linear bot user`：创建/指定用户、加入相关团队、切到该用户身份生成 API key。  
   接受 key 前，务必让我确认它来自机器人用户而非个人。记录 bot user id。  

4. OpenAI + Anthropic API key。  
   问是否已有各自账号下启用了计费的 API key。若无，发我对应页面链接让我去创建。  

5. Linear webhook。  
   此步稍后进行，bootstrap 打印服务地址后，再添加 webhook 指向 `${Service URL}/webhooks/linear`，用自动生成的 `broccoli-oss-linear-webhook-secret`，订阅 Issue 与 Issue label 事件。现在无需操作。  

6. Secret Manager 填充。  
   目标项目存在后，对四个需人工管理的 secret（`broccoli-oss-github-app-private-key-pem`、`broccoli-oss-linear-api-key`、`broccoli-oss-openai-api-key`、`broccoli-oss-anthropic-api-key`）  
   给我每个 secret 在目标项目 Secret Manager 控制台的精确 URL，并等我确认都已存在 `latest` 版本。  
   自动生成的 webhook 与 DB 密码 secret 由 bootstrap 处理，我无需操作。  

完成以上后：  
- 先做只读“发现”步骤，若缺失 `gcloud` 认证、计费权限、组织/项目权限或本地工具，立即报错。  
- 若我尚无目标 GCP 项目，先创建/准备好。  
- 云变更前，展示最终部署计划与任何缺失的非 secret 输入。  
- 绝不让我把 secret 粘进聊天。若缺失，只告诉我需在目标项目 Secret Manager 里填充的 secret 名称，并等我确认已存在。  
- 优先用仓库已有部署脚本、文档默认值与部署后检查，而非猜测。  
- 默认走 Cloud Build 而非本地 Docker。  
- 部署后，继续执行可安全运行的验证步骤，最后报告服务地址、剩余手动步骤（含第 5 点的 Linear webhook）与冒烟测试结果。  

想手动一步步部署？继续看下方指南，它从项目创建讲起，并标出必须手动完成的环节。

— ## 目录 - 架构一览 - 前置条件 - 部署到你的 GCP - 0. 创建或选择 GCP 项目 - 1. 创建 GitHub App - 2. 指定 Linear 机器人用户 - 3. 打开正确项目的 Secret Manager - 4. 添加所需 secret 值 - 5. 用 Cloud Build 构建并推送镜像 - 6. 运行 bootstrap - 7. 在仓库安装 GitHub App - 8. 运行迁移并初始化仓库配置 - 9. 注册 webhook - 10. 运行预检 - 11. 跑冒烟测试 - 运维 Broccoli - 查看任务状态 - 被忽略的 webhook 响应 - 安全重试失败的 webhook - IAM - 本地开发 - 文档 - 贡献 - 许可证 - FAQ — ## 架构一览 Broccoli 以两个 Cloud Run 工作负载 + 共享 Postgres 的形式运行：

完整设计见 ARCHITECTURE.md，webhook 与状态模型见 JOB-CONTRACT.md。

前置条件

• 一个可创建/管理项目并绑定计费的 Google Cloud 账号。
• 该账号下 gcloud 已认证。无需提前知道最终项目 ID。
• 浏览器可访问 GitHub、Linear 与 GCP 控制台。多个首次配置步骤需手动，因为所需值位于这些平台，不应粘进聊天。
• 若故意不用 Cloud Build，则需 Docker + buildx。
• Python 3.12+ 与 uv (https://github.com/astral-sh/uv) 用于运维工具（迁移、初始化、预检）。
• Anthropic API key 与 OpenAI（或 Codex）API key，或能自行创建。

部署到你的 GCP

以下流程面向首次操作者，从零开始，说明值从哪里来，并标出必须手动完成的安全步骤。

0. 创建或选择 GCP 项目

需先有项目才能放 secret 与部署 Cloud Run。

若已有项目：

1. 在 GCP 控制台打开项目。
2. 记录 Project ID，后续使用。
3. 确认已绑定计费。

若尚无项目：

1. 打开 Google Cloud“管理资源”页：。
2. 创建项目，或用 broccoli-oss-gcp-deploy 技能代建。
3. 在计费项目页绑定计费：。
4. 记录新的 Project ID。

用 Codex 部署技能可一条龙完成项目创建、计费绑定、所需 API 启用与 Secret Manager 容器准备，对新手最友好。

1. 创建 GitHub App

用 GitHub App（而非 PAT）以便 Broccoli 签发安装令牌。

仓库权限：

• Contents: read/write
• Pull requests: read/write
• Issues: read/write
• Metadata: read-only

订阅事件： Pull request review

此时 Homepage URL 与 Webhook URL 可填占位符，第 6 步打印真实地址后再更新。

记录 App ID 并下载 私钥 PEM。

• GitHub App ID 是 GitHub 分配的数字标识，deploy/bootstrap.sh 会把它传给服务与 runner 用于签发安装令牌。
• GitHub App 私钥 PEM 在 GitHub App 设置页生成，与 App ID 一起用于以 App 身份认证。
• PEM 文件留在本地，不要粘进聊天。

2. 指定 Linear 机器人用户

Broccoli 在 issue 被指派给特定用户时触发。

1. 创建或指定一个专用 Linear 用户作为 Broccoli 机器人。
2. 把该用户加入所有需要走 Broccoli 的团队。
3. 用该用户身份生成可读写 issue、评论、标签的 API key。
4. 记录 bot user id，第 8 步会写进 global_config。

3. 打开正确项目的 Secret Manager

首次用 GCP 常卡在这一步：secret 必须放进你的部署项目里的 Google Cloud Secret Manager。

1. 打开 Secret Manager：。
2. 用页面顶部项目选择器切到 Broccoli 部署项目。
3. 确认项目 ID 与第 0 步记录的一致。
4. 若用 Codex 部署技能准备过项目，部分 secret 容器可能已存在，没问题，打开后点添加新版本即可，无需重复创建。

4. 添加所需 secret 值

这些值来自 GitHub、Linear、OpenAI、Anthropic，需手动录入，不要粘进聊天。在 GCP 控制台或你自己的终端里完成。

对每个 secret：

1. 在 Secret Manager 点创建 secret 或打开同名现有 secret。
2. 使用下方列出的精确名称。
3. 粘贴值或上传文件内容。
4. 保存并确认 secret 出现 latest 版本。

bootstrap 前必须提供：

若走纯 shell 路径，还需手动创建：

用 broccoli-oss-gcp-deploy 助手可在项目创建后自动生成 broccoli-oss-db-password、broccoli-oss-gh-webhook-secret、broccoli-oss-linear-webhook-secret。上面四个 operator 管理的 secret 仍需你自己提供。

默认 Cloud SQL 路径：

• 无需预填 broccoli-oss-database-url，deploy/bootstrap.sh 会根据 Cloud SQL 连接名与 DB 密码推导并写入。
• 但需提供 broccoli-oss-db-password，作为 Cloud SQL 数据库用户密码，应使用高熵随机串。

本地开发或自定义部署时，runner 也接受 CODEX_API_KEY 替代 OPENAI_API_KEY。

5. 用 Cloud Build 构建并推送镜像

cd path/to/this-repo  
export GCP_PROJECT_ID=your-project  
export GCP_REGION=us-central1  
export TAG=v0.1.0  
export PUSH=1  
./deploy/build-and-push.sh  

默认用 Google Cloud Build，即在 GCP 项目内云端构建并推送，无需本地 Docker。脚本会打印 SERVICE_IMAGE=... 与 RUNNER_IMAGE=...，供下一步复制使用。

若故意本地 Docker 构建：

export BUILD_BACKEND=docker  
./deploy/build-and-push.sh  

6. 运行 bootstrap

deploy/bootstrap.sh 幂等，使用增量 Cloud Run 环境/secret 更新，可反复执行。

export GCP_PROJECT_ID=your-project  
export GCP_REGION=us-central1  
export GITHUB_APP_ID=123456  
export SERVICE_IMAGE=us-docker.pkg.dev/your-project/containers/broccoli-oss-service:v0.1.0  
export RUNNER_IMAGE=us-docker.pkg.dev/your-project/containers/broccoli-oss-runner:v0.1.0  

# 常用可选覆盖：  
export INGRESS_SERVICE_NAME=broccoli-oss-service  
export RUNNER_JOB_BASENAME=broccoli-oss-runner  
export RUNNER_TIMEOUT_SECONDS=3600  
export DB_BACKEND=cloudsql  
export DB_INSTANCE_NAME=broccoli-oss-pg  
export DB_AUTHORIZED_NETWORKS=0.0.0.0/0  

./deploy/bootstrap.sh  

Bootstrap 会打印：

• 部署后的 service URL
• **GitHub webho