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:

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 have a project yet:

1. Open the Google Cloud "Manage resources" page: https://console.cloud.google.com/cloud-resource-manager.
2. Create a project, or use the broccoli-oss-gcp-deploy skill to create one for you.
3. Attach billing on the billing projects page: https://console.cloud.google.com/billing/projects.
4. 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.

1. Create or designate a dedicated Linear user to act as the Broccoli bot.
2. Give that user access to every team whose issues should be routed through Broccoli.
3. Generate a Linear API key scoped to a user or token that can read issues, comments, and labels for those teams.
4. 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.

1. Open Secret Manager: https://console.cloud.google.com/security/secret-manager.
2. Use the project selector at the top of the page to switch to your Broccoli deployment project.
3. Confirm the selected project ID matches the one you recorded in Step 0.
4. If you used the Codex deployment skill to prepare the project, some or all secret containers may already exist. That is fine. You can open an existing secret and click Add new version instead of creating it again.

4. Add the required secret values

These values must be entered manually because they come from GitHub, Linear, OpenAI, and Anthropic accounts that the deploy helper cannot safely read on your behalf. Do not paste secret values into chat. Add them in Secret Manager through the GCP Console or from your own terminal.

For each secret below:

1. In Secret Manager, either click Create secret or open the existing secret with the same name.
2. Use the exact secret name shown below.
3. Paste the value or upload the file contents.
4. Save it and confirm the secret now has a latest version.

Required before bootstrap:

Optional to create manually if you are following the raw shell path in this README:

If you are using the broccoli-oss-gcp-deploy helper, it can auto-generate broccoli-oss-db-password, broccoli-oss-gh-webhook-secret, and broccoli-oss-linear-webhook-secret after the project exists. You still need to provide the four operator-managed secrets above yourself.

For the default Cloud SQL path:

• You do not pre-populate broccoli-oss-database-url. deploy/bootstrap.sh derives it from the Cloud SQL connection name and the DB password, then writes that secret for you.
• You do need broccoli-oss-db-password. It is the Cloud SQL database user's password and should be a random high-entropy string.

For local development or custom deployments, the runner also accepts CODEX_API_KEY instead of OPENAI_API_KEY.

5. Build and push images with 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

By default, deploy/build-and-push.sh uses Google Cloud Build. That means Google builds and pushes the images inside your GCP project, so you do not need local Docker for the recommended deploy path.

The script prints SERVICE_IMAGE=... and RUNNER_IMAGE=... so you can copy them into the next step.

If you intentionally want to build locally with Docker instead, set:

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

6. Run bootstrap

deploy/bootstrap.sh is idempotent and uses incremental Cloud Run env/secret updates, so you can safely re-run it.

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

# Common optional overrides:
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 prints:

• Deployed service URL
• GitHub webhook URL (${Service URL}/webhooks/github)
• Linear webhook URL (${Service URL}/webhooks/linear)
• Cloud Run service and job resource names

When DB_BACKEND=cloudsql, bootstrap also patches the Cloud SQL instance with a public IPv4 and sets authorizedNetworks from DB_AUTHORIZED_NETWORKS. The default is 0.0.0.0/0, which allows connections from anywhere. Override it with a narrower CIDR list if you want to restrict direct Postgres access.

Go back to your GitHub App settings and set Homepage URL and Webhook URL to the values printed above, then paste the value of broccoli-oss-gh-webhook-secret into the app's webhook secret field.

7. Install the GitHub App on a repo

From the GitHub App settings:

1. Click Install App.
2. Choose the account or org that owns the target repository.
3. Select Only select repositories unless you intentionally want broader scope.
4. Grant access to the target repository.
5. Capture the installation id from the install URL (/settings/installations/<id>) — you'll seed it next.

8. Run migrations and seed repo config

For the default Cloud Run + Cloud SQL deployment, broccoli-oss-database-url is written for the Cloud Run runtime and uses the /cloudsql/... Unix socket path. That secret is correct for the deployed service and runner, but it is not the right value to use directly from your laptop.

For local operator commands, start a local TCP tunnel with Cloud SQL Auth Proxy and build a local DATABASE_URL from broccoli-oss-db-password instead:

cloud-sql-proxy your-project:us-central1:broccoli-oss-pg --port 5432

DB_PASSWORD="$(gcloud secrets versions access latest \
  --secret=broccoli-oss-db-password \
  --project your-project)"
export DATABASE_URL="postgresql://broccoli_oss:${DB_PASSWORD}@127.0.0.1:5432/broccoli_oss"

uv sync --dev
uv run python -m app.operator migrate
uv run python -m app.operator schema-version

If you are using the Codex deployment skill after bootstrap, it should retrieve generated secrets from Secret Manager and use existing target-project credentials where possible instead of telling you to run those helper commands yourself. The commands below remain the manual fallback path.

If you want Codex to finish the operator flow in GCP instead of from your laptop, use:

python .agents/skills/broccoli-oss-gcp-deploy/scripts/deploy.py \
  --github-app-id <github-app-id> \
  --project-id your-project \
  --apply \
  --post-deploy-operator \
  --github-repo-full-name acme/demo \
  [--git-clone-url https://github.com/acme/demo.git] \
  [--default-branch main] \
  [--github-installation-id 12345678] \
  [--linear-team-id <linear-team-id>] \
  [--linear-bot-user-id <linear-bot-user-id>]

That path runs migrate, schema-version, seed, and preflight inside GCP by creating a temporary Cloud Run Job, executing the operator commands there, and deleting the temporary job when it finishes. Any of the optional repo and Linear flags may be omitted when the wrapper can safely discover them from the target project's own secrets and APIs.

You can discover the Linear bot user id and candidate team ids using the target project's existing Linear API key:

LINEAR_API_KEY="$(gcloud secrets versions access latest \
  --secret=broccoli-oss-linear-api-key \
  --project your-project)"

curl -s https://api.linear.app/graphql \
  -H "Authorization: ${LINEAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query":"query ViewerAndTeams { viewer { id name } teams { nodes { id key name } } }"}'

The response includes:

• viewer.id: usually the bot user id when the API key belongs to the bot user
• teams.nodes[].id: candidate linear_team_id values

Edit db/seed/example.seed.yaml (or a copy) with your real values:

repos:
  - repo_key: demo
    enabled: true
    github_repo_full_name: acme/demo
    github_installation_id: 12345678   # from Step 7 install URL /settings/installations/<id>
    git_clone_url: https://github.com/acme/demo.git
    default_branch: main
    base_branch: main
    linear_team_id: <linear-team-uuid>
    config_json: {}

global:
  linear_bot_user_id:
    userId: <linear-bot-user-id>       # from Step 2

Top-level keys supported today: repos and global (with linear_bot_user_id). The seeder rejects duplicate repo_key, duplicate github_repo_full_name, blank required strings, and unknown keys.

uv run python -m app.operator seed --file db/seed/example.seed.yaml

9. Register the webhooks

Retrieve the generated webhook secrets yourself if you need to paste them into GitHub or Linear:

gcloud secrets versions access latest \
  --secret=broccoli-oss-gh-webhook-secret \
  --project your-project

gcloud secrets versions access latest \
  --secret=broccoli-oss-linear-webhook-secret \
  --project your-project

GitHub — the GitHub App webhook is already configured in Step 6; just confirm it points to ${Service URL}/webhooks/github and that the webhook secret matches broccoli-oss-gh-webhook-secret.

Linear — add a new webhook pointing to ${Service URL}/webhooks/linear, using the value of broccoli-oss-linear-webhook-secret. Subscribe to Issue and Issue label events. This step is intentionally manual unless you choose to give Codex an admin-capable Linear credential; the normal bot API key is expected to be non-admin.

Routing rules to know:

• The issue must be assigned to the configured bot user.
• Exactly one routing label must match an enabled repo_key.
• 0 < estimate < 3 selects the small-estimate skill path; everything else uses the default path.

10. Run preflight

Preflight verifies DB connectivity, Secret Manager presence, Cloud Run Job metadata, GitHub App installation token minting for the first enabled repo, Linear API access, and vendored prompt-template integrity.

export GITHUB_APP_ID=123456
export GITHUB_APP_PRIVATE_KEY_PEM="$(gcloud secrets versions access latest \
  --secret=broccoli-oss-github-app-private-key-pem \
  --project your-project)"
export GH_WEBHOOK_SECRET="$(gcloud secrets versions access latest \
  --secret=broccoli-oss-gh-webhook-secret \
  --project your-project)"
export LINEAR_API_KEY="$(gcloud secrets versions access latest \
  --secret=broccoli-oss-linear-api-key \
  --project your-project)"
export LINEAR_WEBHOOK_SECRET="$(gcloud secrets versions access latest \
  --secret=broccoli-oss-linear-webhook-secret \
  --project your-project)"
export RUNNER_JOB_NAME="projects/your-project/locations/us-central1/jobs/broccoli-oss-runner"
export GCP_PROJECT_ID=your-project
export GCP_REGION=us-central1
export APP_BASE_URL=https://your-service-url

uv run python -m app.operator preflight

11. Run the smoke tests

GitHub webhook canary:

APP_BASE_URL=https://your-service-url \
DATABASE_URL=postgresql://... \
GH_WEBHOOK_SECRET=... \
CANARY_GITHUB_REPO_FULL_NAME=acme/demo \
CANARY_GITHUB_PR_NUMBER=12 \
uv run python tests/smoke/github_webhook_canary.py

Linear webhook canary:

APP_BASE_URL=https://your-service-url \
DATABASE_URL=postgresql://... \
LINEAR_WEBHOOK_SECRET=... \
CANARY_LINEAR_ISSUE_ID=issue-id \
CANARY_LINEAR_BOT_USER_ID=bot-user-id \
CANARY_LINEAR_CREATOR_ID=creator-id \
CANARY_LINEAR_REPO_KEY=demo \
uv run python tests/smoke/linear_webhook_canary.py

Both scripts print the HTTP response plus the matching webhook_deliveries row. You're live.

Operating Broccoli

Inspecting job state

Useful tables: webhook_deliveries, jobs, github_pr_state, linear_issue_state, repo_configs, global_config.

SELECT provider, delivery_id, processed_at, ignored_reason, error_stage, job_id
FROM webhook_deliveries
ORDER BY received_at DESC
LIMIT 20;

SELECT id, kind, status, routing_repo_key, error_kind, error_message
FROM jobs
ORDER BY created_at DESC
LIMIT 20;

-- Lifecycle comment and launch metadata (best-effort)
SELECT
  id,
  kind,
  run_metadata->'launch' AS launch,
  run_metadata->'linear'->'commentIds' AS linear_comment_ids,
  run_metadata->'githubReviewFeedback' AS github_review_feedback,
  run_metadata->'run' AS run_stage
FROM jobs
ORDER BY created_at DESC
LIMIT 20;

Lifecycle comments are best-effort side effects. If GitHub/Linear APIs are unavailable or permissions are missing, jobs should still run; run_metadata records what could be posted.

Ignored webhook responses

Every delivery is recorded, including ignored ones, so routing decisions are auditable. Common ignored_reason values:

Retrying a failed webhook safely

Webhook delivery dedupe is stored in Postgres. Safe behavior:

• If the original delivery was already processed, a redelivery returns duplicate_delivery.
• If the original job record exists but launch bookkeeping failed, a redelivery reuses the stored job id.
• Do not manually mutate jobs or webhook_deliveries rows unless you are intentionally repairing state.

Preferred retry path:

1. Fix the root cause.
2. Redeliver the original webhook from GitHub or Linear.
3. Confirm the same delivery id reaches a terminal job state.

IAM

Broccoli prefers "works on the first deploy" over the strictest least-privilege model. Tighten after you're live.

Runtime service accounts:

• Ingress service account: project-level roles/run.developer
• Ingress + runner service accounts: roles/secretmanager.secretAccessor
• Ingress + runner service accounts: roles/cloudsql.client (only when using Cloud SQL)

Deployer permissions: project Owner or Editor, plus permission to create service accounts and IAM bindings.

Reference docs consulted for IAM decisions:

• Cloud Run: Create jobs
• Cloud Run: Execute jobs
• Cloud Run IAM roles and permissions

Local development

uv sync --dev
cp .env.example .env   # fill in real values; never commit .env
uv run ruff check .
uv run pytest

The .env file is gitignored. See CONTRIBUTING.md for the full contributor workflow.

Documentation

• ARCHITECTURE.md — design, components, data flow
• JOB-CONTRACT.md — webhook and state-model contract
• CONTRIBUTING.md — how to contribute
• CHANGELOG.md — release history

Lifecycle comment parity notes:

• Linear issue automation posts best-effort lifecycle comments (enqueued, started, prOpened, terminal).
• GitHub review-feedback jobs post a best-effort "launcher started" comment and a terminal failure comment.
• Other private-repo behaviors (debug mode, plan-verbatim mode, extra remediation flows) are intentionally out of scope.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md for setup, expectations, and the review loop. Do not post secrets, credentials, or other sensitive deployment details in public issues.

License

Broccoli OSS is released under the MIT License. Bundled third-party notices are in NOTICE.

FAQ

Can I use an externally managed Postgres? Yes — set DB_BACKEND to anything other than cloudsql and point DATABASE_URL at your instance.

Can I swap out the LLMs? The runner shells out to the codex and claude CLIs; swapping requires forking the runner handlers and the vendored prompt templates. Contributions that make this pluggable are welcome.

Is there a hosted version? Not today. Broccoli runs in your own GCP project against your own keys.

Is there a closed-source variant? A closed-source variant of Broccoli running on different infrastructure exists and is not published here. The OSS path in this repo is self-contained and production-ready.