GitHub - besimple-oss/broccoli: Broccoli turns Linear tickets into shipped PRs — powered by Claude and Codex, running on your own Google Cloud.
Pangram verdict · v3.3
We believe that this document is primarily human-written, with some AI-generated content detected
AI likelihood · overall
MixedArticle text · 1,661 words · 5 segments analyzed
AI teammates for your engineering loop. Broccoli turns Linear tickets into shipped PRs — powered by Claude and Codex, running on your own Google Cloud.
Why Broccoli
🎯 Linear ticket → reviewable PR. Assign an issue to the Broccoli bot and watch it plan, implement, and open a pull request while you sleep. 🔒 Your infra. Your keys. Your data. Deployed to your GCP project against your Postgres. No third-party control plane, no data leaving your tenancy. 🧱 Production-grade on day one. Serverless Cloud Run + Secret Manager + webhook dedupe + durable job state. No toy. 🧩 Own your prompts. Start with our opinionated prompt templates. Fork, tune, and version them with your code. ⚡ AI code review on every PR. Claude and Codex read your diffs, leave actionable comments, and push fix commits when you ask. 🛠️ Deploys in ~30 minutes. One bootstrap script. One config file. Two webhooks. Ship.
Use This With a Coding Agent Paste the following prompt to your favorite coding agent. Ours is codex cli. Deploy this repository to my Google Cloud project.
If I only gave you the GitHub repo URL, clone the repo first. If I already opened the repo locally, work from the existing checkout.
Use the repo's deployment instructions, scripts, and `.agents/skills/broccoli-oss-gcp-deploy/SKILL.md`. Treat this as a request to deploy the app, not just inspect the codebase.
Do not assume I have any of the prerequisites done yet. Before discovery, walk me through these checkpoints one at a time, and for each one confirm my answer before moving on. If a section of the README covers the step, point me to it instead of re-explaining.
1. GCP project + billing. Ask whether I already have a Google Cloud project with billing attached, and whether `gcloud` is logged in to that account. If not, walk me through creating the project at https://console.cloud.google.com/cloud-resource-manager and attaching billing at https://console.cloud.google.com/billing/projects, or offer to have the deployment skill create the project for me. Record the Project ID. 2. GitHub App.
Ask whether I have already created a GitHub App for Broccoli with the required permissions (Contents, Pull requests, Issues = read/write; Metadata = read-only; subscribed to the `Pull request review` event). If not, walk me through `README.md -> Deploy it on your GCP -> 1. Create a GitHub App` step by step. Have me record the numeric App ID and download the private key PEM file locally. Placeholder Homepage/Webhook URLs are fine for now; bootstrap will print the real URLs. 3. Linear bot user + API key. IMPORTANT: the Linear API key must belong to a dedicated Linear bot user, NOT my personal account. A personal key silently breaks the "issue assigned to bot triggers a run" flow. Ask whether a dedicated bot user already exists. If not, walk me through `README.md -> 2. Designate a Linear bot user`: create or designate a Linear user, add it to every team whose issues should route through Broccoli, then log in as that bot user (or have an admin switch to that user) and generate the API key from that user's settings page. Before you accept the key as ready, explicitly confirm with me that it came from the bot user and not from my personal account. Record the bot user id. 4. OpenAI + Anthropic API keys. Ask whether I already have active API keys with billing enabled on each account. If not, send me to the OpenAI and Anthropic API keys pages to create them. 5. Linear webhook. This one comes later and is configured after bootstrap prints the service URL. Just tell me now that once the service URL exists, I will add a Linear webhook pointing at `${Service URL}/webhooks/linear` using the auto-generated `broccoli-oss-linear-webhook-secret` and subscribe to Issue and Issue label events. I do not need to do anything for this step yet. 6. Secret Manager population. Once the target project exists, for each of the four operator-managed secrets (`broccoli-oss-github-app-private-key-pem`, `broccoli-oss-linear-api-key`, `broccoli-oss-openai-api-key`, `broccoli-oss-anthropic-api-key`) give me the exact Secret Manager console URL for the target project and pause until I confirm each secret has a `latest` version.
You retrieve the auto-generated webhook and DB password secrets yourself after bootstrap; I do not touch those.
Workflow after the checkpoints above: - Run a non-mutating discovery step and fail fast on missing `gcloud` auth, billing access, org or project permissions, or other required local tools. - If I do not already have a target GCP project, create or prepare one first. - Before making cloud changes, show me the resolved deployment plan and any missing non-secret inputs. - Never ask me to paste secrets into chat. If required secrets are missing, tell me exactly which secret names I need to populate in the target project and pause until I confirm they are present. - Prefer the repo's existing deploy scripts, documented defaults, and post-deploy checks over guesswork. - Use the Cloud Build path by default instead of local Docker. - After deployment, continue through the verification steps you can safely run, then report the service URL, any remaining manual setup (including the Linear webhook from checkpoint 5), and the smoke-test result.
This is the fast path if you want the agent to drive the deployment for you. If you want the manual step-by-step path instead, use the guide below; it starts from project creation and shows exactly where the manual setup happens.
Table of contents
Architecture at a glance Prerequisites Deploy it on your GCP
0. Create or choose a GCP project 1. Create a GitHub App 2. Designate a Linear bot user 3. Open Secret Manager in the right project 4. Add the required secret values 5. Build and push images with Cloud Build 6. Run bootstrap 7. Install the GitHub App on a repo 8. Run migrations and seed repo config 9. Register the webhooks 10. Run preflight 11.
Run the smoke tests
Operating Broccoli
Inspecting job state Ignored webhook responses Retrying a failed webhook safely
IAM Local development Documentation Contributing License FAQ
Architecture at a glance Broccoli runs as two Cloud Run workloads over a shared Postgres:
Component Role
broccoli-oss-service FastAPI service that receives GitHub and Linear webhooks, verifies signatures, dedupes deliveries, and creates job records.
broccoli-oss-runner Cloud Run Job that executes automation using the codex and claude CLIs against vendored prompt templates.
Postgres Durable state for jobs, webhook deliveries, PR state, Linear issue state, and repo config.
Secret Manager Holds the GitHub App private key, webhook secrets, LLM API keys, and database URL.
See ARCHITECTURE.md for the full design and JOB-CONTRACT.md for the webhook and state-model contract. Prerequisites
A Google Cloud account that can either create a new project and attach billing, or administer an existing project. gcloud authenticated to that Google Cloud account. You do not need to know the final project ID before starting. Browser access to GitHub, Linear, and the GCP Console. Several first-time setup steps are intentionally manual because the required values live in those products and should not be pasted into chat. Docker with buildx only if you intentionally want to build images locally instead of using the default Cloud Build path. Python 3.12+ and uv for operator tooling (migrations, seed, preflight). An Anthropic API key and an OpenAI (or Codex) API key, or the ability to create them.
Deploy it on your GCP The sequence below is written for a first-time operator. It starts from zero, explains where values come from, and calls out the steps that must still happen manually for security reasons. 0. Create or choose a GCP project You need a Google Cloud project before you can add Broccoli secrets or deploy Cloud Run services. If you already have a project you want to use:
Open the project in the GCP Console. Record the Project ID. You will use this in later steps.
Confirm billing is attached to that project.
If you do not have a project yet:
Open the Google Cloud "Manage resources" page: https://console.cloud.google.com/cloud-resource-manager. Create a project, or use the broccoli-oss-gcp-deploy skill to create one for you. Attach billing on the billing projects page: https://console.cloud.google.com/billing/projects. Record the new Project ID.
If you are using the Codex deployment skill, it can create the project, attach billing, enable the required APIs, and create the Secret Manager secret containers for you. That is often the easiest path for a first-time operator because it gives you a real project to click into before you need to add any secrets. 1. Create a GitHub App Use a GitHub App (not a PAT) so Broccoli can mint scoped installation tokens. Repository permissions:
Contents: read/write Pull requests: read/write Issues: read/write Metadata: read-only
Subscribe to events: Pull request review. At this stage, set Homepage URL and Webhook URL to placeholders. You will update them after Step 6 prints the real service URL. Record the App ID and download a private key PEM.
GitHub App ID is the numeric identifier GitHub assigns to the app. deploy/bootstrap.sh passes it to the service and runner so they can mint installation tokens. GitHub App private key PEM is the private key file you generate in the GitHub App settings page. Broccoli uses it together with the App ID to authenticate to GitHub as the app. Keep the PEM file local. Do not paste it into chat.
2. Designate a Linear bot user Broccoli triggers when an issue is assigned to a specific Linear user.
Create or designate a dedicated Linear user to act as the Broccoli bot. Give that user access to every team whose issues should be routed through Broccoli. Generate a Linear API key scoped to a user or token that can read issues, comments, and labels for those teams. Record the bot user id. You will seed it into global_config in Step 8.
3. Open Secret Manager in the right project If this is your first time using GCP, this is the step that usually causes confusion: the secrets go into Google Cloud Secret Manager inside your deployment project.
Open Secret Manager: https://console.cloud.google.com/security/secret-manager.