🥦 Broccoli OSS

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 repository permissions (Contents, Pull requests, Issues = read/write; Metadata = read-only) and the required webhook event subscriptions: `Pull request review` for review-feedback automation, plus `Pull request` if I also want Broccoli to react when PRs are opened, updated, reopened, or marked ready for review. Call out that on GitHub, repository permissions and webhook events are separate settings — the `Pull requests` permission alone does not subscribe the App to PR events. 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 by default; optionally launched inside Blaxel sandboxes when EXECUTION_BACKEND=blaxel. 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:

1. Open the project in the GCP Console.
2. Record the Project ID. You will use this in later steps.
3. Confirm billing is attached to that project.

If you do not ha