AI 隊友加入您的工程循環。Broccoli 將 Linear 任務轉化為已合併的 PR — 由 Claude 和 Codex 提供支援，運行在您自有的 Google Cloud 或 Blaxel 容器中。

若要代理部署，請將以下提示貼到您最愛的程式碼代理工具。我們的首選是 codex cli。

如果您希望代理工具為您處理部署事宜，這是最快速的路徑。如果您偏好手動逐步操作，請使用下方的指南；它從專案建立開始，並精確說明手動設定的發生位置。

Broccoli 作為兩個 Cloud Run 工作負載運行，共享一個 Postgres 資料庫：

請參閱 ARCHITECTURE.md 以取得完整設計，以及 JOB-CONTRACT.md 以取得 webhook 和狀態模型合約。

下方的順序是為首次操作者編寫的。它從零開始，解釋數值來源，並標示出因安全原因必須手動完成的步驟。

在新增 Broccoli 機密或部署 Cloud Run 服務之前，您需要一個 Google Cloud 專案。

如果您已有想使用的專案：

如果您使用 Codex 部署技能，它可以為您建立專案、附加計費、啟用所需 API，並建立 Secret Manager 的機密容器。這通常是首次操作者最簡單的路徑，因為它能在您需要新增任何機密之前，提供一個可供點擊進入的實際專案。

請使用 GitHub App（而非 PAT），以便 Broccoli 可以鑄造範圍限定的安裝權杖。

在此階段，請將 Homepage URL 和 Webhook URL 設定為預留位置。您將在步驟 6 印出實際服務 URL 後更新它們。請記錄 App ID 並下載私鑰 PEM。

Broccoli 在問題被指派給特定的 Linear 使用者時觸發。

如果您是首次使用 GCP，這一步通常會造成混淆：機密會進入您部署專案內的 Google Cloud Secret Manager。

這些值必須手動輸入，因為它們來自 GitHub、Linear、OpenAI 和 Anthropic 帳戶，部署助手無法為您安全地讀取。請勿將機密值貼到聊天中。請透過 GCP Console 或您自己的終端機在 Secret Manager 中新增它們。

如果您遵循此 README 中的原始 shell 路徑，則此步驟可選擇手動建立：

如果您使用 broccoli-oss-gcp-deploy 助手，它可以在專案存在後自動生成 broccoli-oss-db-password、broccoli-oss-gh-webhook-secret 和 broccoli-oss-linear-webhook-secret。您仍然需要自行提供上述四個操作者管理的機密。

預設情況下，deploy/build-and-push.sh 使用 Google Cloud Build。這表示 Google 會在您的 GCP 專案內建置並推送映像檔，因此推薦的部署路徑不需要本機 Docker。

該腳本會印出 SERVICE_IMAGE=... 和 RUNNER_IMAGE=...，以便您將它們複製到下一個步驟。

如果您有意願在本機使用 Docker 建置，請設定：

deploy/bootstrap.sh 是冪等的，並使用遞增的 Cloud Run 環境/機密更新，因此您可以安全地重新運行它。

預設情況下，部署會保留現有的 Cloud Run Jobs 執行路徑 (EXECUTION_BACKEND=cloud_run_jobs)。若要選擇使用 Blaxel 沙盒，請在服務上設定 EXECUTION_BACKEND=blaxel，並確保在重新啟動服務前存在可選的 Blaxel 環境變數。

當 DB_BACKEND=cloudsql 時，bootstrap 也會使用公用 IPv4 修補 Cloud SQL 執行個體，並從 DB_AUTHORIZED_NETWORKS 設定 authorizedNetworks。預設值為 0.0.0.0/0，允許從任何地方連線。如果您想限制直接的 Postgres 存取，請使用更窄的 CIDR 列表進行覆蓋。

回到您的 GitHub App 設定，將 Homepage URL 和 Webhook URL 設定為上方印出的值，然後將 broccoli-oss-gh-webhook-secret 的值貼到 App 的 webhook 機密欄位。

對於預設的 Cloud Run + Cloud SQL 部署，broccoli-oss-database-url 是為 Cloud Run 執行階段編寫的，並使用 /cloudsql/... Unix 套接字路徑。該機密對於已部署的服務和運行器是正確的，但它不是直接從您的筆記型電腦使用的正確值。

對於本機操作者命令，請使用 Cloud SQL Auth Proxy 啟動本機 TCP 隧道，並從 broccoli-oss-db-password 建置本機 DATABASE_URL：

如果您在 bootstrap 後使用 Codex 部署技能，它應該會從 Secret Manager 擷取生成的機密，並盡可能使用現有的目標專案憑證，而不是告訴您自行運行這些助手命令。下方的命令仍然是手動備用路徑。

如果您希望 Codex 在 GCP 中完成操作者流程，而不是從您的筆記型電腦執行，請使用：

該路徑透過建立一個臨時的 Cloud Run Job，在其中執行操作者命令，並在臨時 Job 完成後刪除它，來運行 migrate、schema-version、seed 和 preflight。當包裝器可以安全地從目標專案自身的機密和 API 發現任何可選的儲存庫和 Linear 標誌時，可以省略它們。

您可以使用目標專案現有的 Linear API 金鑰來發現 Linear bot 使用者 ID 和候選團隊 ID：

編輯 db/seed/example.seed.yaml（或其副本），填入您的實際值：

目前支援的頂級金鑰：repos 和 global（包含 linear_bot_user_id）。種子產生器會拒絕重複的 repo_key、重複的 github_repo_full_name、空白的必要字串和未知的金鑰。

如果您需要將生成的 webhook 機密貼到 GitHub 或 Linear，請自行擷取：

Preflight 會驗證 DB 連線、Secret Manager 的存在、特定後端的執行先決條件（預設為 Cloud Run Job 中繼資料，或當 EXECUTION_BACKEND=blaxel 時的 Blaxel 環境變數 + 機密解析）、第一個啟用儲存庫的 GitHub App 安裝權杖鑄造、Linear API 存取權，以及套件提示範本的完整性。

EXECUTION_BACKEND 預設為 cloud_run_jobs。僅當您希望 webhook 觸發和推廣的 Job 在 Blaxel 沙盒中運行，而不是在 Cloud Run Jobs 中運行時，才將其設定為 blaxel。

必要的服務模式 Blaxel LLM 機密選擇器環境變數：

Blaxel 沙盒運行器的映像檔要求：

這兩個腳本都會印出 HTTP 回應以及匹配的 webhook_deliveries 列。您已上線。

有用的表格：webhook_deliveries、jobs、github_pr_state、linear_issue_state、repo_configs、global_config。

生命週期註解是盡力而為的副作用。如果 GitHub/Linear API 無法使用或權限不足，Job 仍應運行；run_metadata 會記錄可以發布的內容。

每次傳遞都會被記錄，包括被忽略的傳遞，因此路由決策是可審計的。常見的 ignored_reason 值：

Webhook 傳遞去重儲存在 Postgres 中。安全行為：

Broccoli 偏好「首次部署即可工作」而非最嚴格的最小權限模型。上線後再收緊。

部署者權限：專案 Owner 或 Editor，以及建立服務帳戶和 IAM 綁定的權限。

IAM 決策參考文件：

.env 文件被 gitignore。請參閱 CONTRIBUTING.md 以取得完整的貢獻者工作流程。

歡迎提交 Issues 和 Pull Requests。請從 CONTRIBUTING.md 開始了解設定、預期和審查流程。請勿在公開的 Issues 中發布機密、憑證或其他敏感的部署細節。

Broccoli OSS 在 MIT 授權條款下發布。包含的第三方通知請參閱 NOTICE。

我可以使用外部管理的 Postgres 嗎？是的 — 將 DB_BACKEND 設定為 cloudsql 以外的任何值，並將 DATABASE_URL 指向您的執行個體。

我可以更換 LLM 嗎？運行器會呼叫 codex 和 claude CLI；更換需要 fork 運行器處理程序和套件提示範本。歡迎對使其可插拔的貢獻。

有託管版本嗎？目前沒有。Broccoli 在您自己的 GCP 專案中，使用您自己的金鑰運行。

有閉源變體嗎？存在一個運行在不同基礎設施上的閉源 Broccoli 變體，但未在此處發布。此儲存庫中的 OSS 路徑是獨立且生產就緒的。

Broccoli 將 Linear 任務轉化為已合併的 PR — 由 Claude 和 Codex 提供支援，運行在您自有的 Google Cloud 或 Blaxel 容器中。