🥦 Broccoli OSS

당신의 엔지니어링 루프를 위한 AI 팀원.
Broccoli는 Claude와 Codex를 기반으로 작동하며, 사용자의 Google Cloud에서 실행되어 Linear 티켓을 배포 가능한 PR(Pull Request)로 변환합니다.

</div>

Why Broccoli (왜 Broccoli인가)

🎯 Linear 티켓 → 검토 가능한 PR. 이슈를 Broccoli 봇에 할당하면, 당신이 자는 동안 봇이 계획을 세우고, 구현하고, Pull Request를 생성하는 과정을 지켜보세요.
🔒 당신의 인프라. 당신의 키. 당신의 데이터. 당신의 Postgres를 사용하여 당신의 GCP(Google Cloud Platform) 프로젝트에 배포됩니다. 제3자의 컨트롤 플레인(Control Plane)이 없으며, 데이터가 당신의 테넌시(Tenancy)를 벗어나지 않습니다.
🧱 첫날부터 프로덕션급 성능. Serverless Cloud Run + Secret Manager + webhook 중복 제거 + 내구성이 있는 작업 상태(Durable job state). 장난감이 아닙니다.
🧩 프롬프트(Prompt)를 직접 소유하세요. 우리의 정교한 프롬프트 템플릿으로 시작하세요. 코드를 통해 이를 포크(Fork)하고, 조정하고, 버전 관리할 수 있습니다.
⚡ 모든 PR에 대한 AI 코드 리뷰. Claude와 Codex가 Diff(차이점)를 읽고, 실행 가능한 코멘트를 남기며, 요청 시 수정 커밋(Fix commit)을 푸시합니다.
🛠️ 약 30분 만에 배포 완료. 하나의 부트스트랩(Bootstrap) 스크립트. 하나의 설정 파일. 두 개의 웹훅(Webhook). 바로 배포하세요.

Use This With a Coding Agent (코딩 에이전트와 함께 사용하기)

당신이 선호하는 코딩 에이전트에 다음 프롬프트를 붙여넣으세요. 우리의 선택은 codex cli입니다.

이 저장소를 나의 Google Cloud 프로젝트에 배포해줘.

만약 내가 GitHub 저장소 URL만 제공했다면, 먼저 저장소를 클론(Clone)해줘. 만약 내가 이미 로컬에서 저장소를 열었다면, 기존의 체크아웃(Checkout) 상태에서 작업해줘.
...

에이전트가 배포를 대신 수행하도록 하고 싶다면 이것이 가장 빠른 방법입니다. 대신 수동으로 단계별 진행을 원한다면 아래 가이드를 사용하세요. 프로젝트 생성부터 시작하여 수동 설정이 정확히 어디에서 이루어지는지 보여줍니다.

Table of contents (목차)

Architecture at a glance (아키텍처 개요)

Broccoli는 공유 Postgres를 통해 두 개의 Cloud Run 워크로드를 사용하여 실행됩니다:

Component	Role
`broccoli-oss-service`	GitHub 및 Linear 웹훅을 수신하고, 시그니처를 검증하며, 전송 건수를 중복 제거하고, 작업 레코드를 생성하는 FastAPI 서비스.
...

전체 설계는 ARCHITECTURE.md에서, 웹훅 및 상태 모델 계약은 JOB-CONTRACT.md에서 확인하세요.

Prerequisites (사전 준비 사항)

새 프로젝트를 생성하고 결제(Billing)를 연결하거나, 기존 프로젝트를 관리할 수 있는 Google Cloud 계정.
해당 Google Cloud 계정으로 인증된 gcloud.
시작하기 전에 최종 프로젝트 ID(Project ID)를 미리 알 필요는 없습니다.
GitHub, Linear, 그리고 GCP 콘솔(Console)에 접속 가능한 브라우저. 몇 가지 초기 설정 단계는 의도적으로 수동으로 진행됩니다. 이는 필요한 값들이 해당 제품 내에 존재하며, 채팅창에 붙여넣어서는 안 되기 때문입니다.
기본 Cloud Build 경로 대신 의도적으로 이미지를 로컬에서 빌드하고자 하는 경우에만 buildx가 포함된 Docker가 필요합니다.
운영 도구(마이그레이션(Migrations), 시드(Seed), 사전 점검(Preflight))를 위한 Python 3.12+ 및 uv.
Anthropic API 키와 OpenAI (또는 Codex) API 키, 또는 이를 생성할 수 있는 권한.

GCP에 배포하기

아래의 순서는 처음 사용하는 운영자를 위해 작성되었습니다. 아무것도 없는 상태에서 시작하며, 값이 어디에서 오는지 설명하고, 보안상의 이유로 여전히 수동으로 진행해야 하는 단계들을 명시합니다.

0. GCP 프로젝트 생성 또는 선택

Broccoli 비밀 값(Secrets)을 추가하거나 Cloud Run 서비스를 배포하기 전에 Google Cloud 프로젝트가 필요합니다.

이미 사용하려는 프로젝트가 있는 경우:

GCP 콘솔에서 해당 프로젝트를 엽니다.
**프로젝트 ID (Project ID)**를 기록합니다. 이후 단계에서 이 ID를 사용하게 됩니다.
해당 프로젝트에 결제(Billing)가 연결되어 있는지 확인합니다.

아직 프로젝트가 없는 경우:

Google Cloud "리소스 관리(Manage resources)" 페이지를 엽니다: https://console.cloud.google.com/cloud-resource-manager.
프로젝트를 생성하거나, broccoli-oss-gcp-deploy 스킬을 사용하여 프로젝트를 생성합니다.
결제 프로젝트 페이지에서 결제를 연결합니다: https://console.cloud.google.com/billing/projects.
새로운 **프로젝트 ID (Project ID)**를 기록합니다.

Codex 배포 스킬 (deployment skill)을 사용 중이라면, 프로젝트 생성, 결제 연결, 필요한 API 활성화, 그리고 Secret Manager 비밀 컨테이너 생성을 자동으로 수행할 수 있습니다. 이는 처음 사용하는 운영자에게 가장 쉬운 방법인 경우가 많은데, 비밀값(secrets)을 추가하기 전에 실제로 클릭하여 확인할 수 있는 프로젝트를 미리 만들어 주기 때문입니다.

1. GitHub App 생성

Broccoli가 범위가 제한된 설치 토큰 (scoped installation tokens)을 발행할 수 있도록 GitHub App (PAT가 아님)을 사용하세요.

저장소 권한 (Repository permissions):

Contents: read/write
Pull requests: read/write
Issues: read/write
Metadata: read-only
Pull request review — 필수; 리뷰-피드백 자동화를 구동합니다.
Pull request — Broccoli가 PR이 열리거나, 업데이트되거나, 다시 열리거나, 리뷰 준비 상태로 표시될 때 반응하게 하려면 필수입니다.

GitHub는 저장소 **권한 (permissions)**과 웹훅 **이벤트 구독 (event subscriptions)**을 별개의 설정으로 취급합니다. 위의 Pull requests 권한은 Broccoli가 PR을 읽고 동작할 수 있게 하는 것이며, 위의 Pull request 이벤트는 PR이 변경되었음을 Broccoli에 알리는 것입니다. PR 오픈 자동화를 위해서는 두 가지 모두가 필요합니다.

이 단계에서는 홈페이지 URL (Homepage URL)과 웹훅 URL (Webhook URL)을 자리 표시자(placeholder)로 설정하세요. 6단계에서 실제 서비스 URL이 출력된 후에 업데이트하게 됩니다. App ID를 기록하고 개인 키 (private key) PEM 파일을 다운로드하세요.

GitHub App ID는 GitHub가 앱에 할당하는 숫자 식별자입니다. deploy/bootstrap.sh는 이를 서비스와 러너 (runner)에 전달하여 설치 토큰을 발행할 수 있도록 합니다.
GitHub App private key PEM은 GitHub App 설정 페이지에서 생성하는 개인 키 파일입니다. Broccoli는 App ID와 함께 이를 사용하여 앱으로서 GitHub에 인증합니다.
PEM 파일은 로컬에 보관하세요. 채팅창에 붙여넣지 마세요.

2. Linear 봇 사용자 지정

Broccoli는 특정 Linear 사용자에게 이슈가 할당될 때 트리거됩니다.

Broccoli 봇 역할을 수행할 전용 Linear 사용자를 생성하거나 지정합니다.
해당 사용자에게 Broccoli를 통해 이슈가 라우팅되어야 하는 모든 팀에 대한 액세스 권한을 부여합니다.
해당 팀들의 이슈, 댓글, 라벨을 읽을 수 있는 권한을 가진 사용자 또는 토큰 범위의 Linear API 키를 생성합니다.
**봇 사용자 ID (bot user id)**를 기록합니다. 이 ID는 8단계의 global_config에 입력(seed)하게 됩니다.

3. 올바른 프로젝트에서 Secret Manager 열기

GCP를 처음 사용하는 경우, 보통 이 단계에서 혼란이 발생합니다. 비밀값(secrets)은 배포 프로젝트 내의 Google Cloud Secret Manager에 저장되어야 합니다.

Secret Manager를 엽니다: https://console.cloud.google.com/security/secret-manager.
페이지 상단의 프로젝트 선택기를 사용하여 Broccoli 배포 프로젝트로 전환합니다.
선택된 프로젝트 ID가 0단계에서 기록한 ID와 일치하는지 확인합니다.
프로젝트 준비를 위해 Codex 배포 스킬 (deployment skill)을 사용했다면, 일부 또는 모든 비밀 컨테이너(secret containers)가 이미 존재할 수 있습니다. 이는 정상입니다. 기존 비밀을 열고 다시 생성하는 대신 **새 버전 추가 (Add new version)**를 클릭하면 됩니다.

4. 필수 비밀값 추가

이 값들은 배포 도우미(deploy helper)가 사용자를 대신하여 안전하게 읽을 수 없는 GitHub, Linear, OpenAI 및 Anthropic 계정에서 가져오기 때문에 반드시 수동으로 입력해야 합니다. 비밀값을 채팅창에 붙여넣지 마세요. GCP 콘솔을 통하거나 본인의 터미널을 통해 Secret Manager에 추가하십시오.

아래 각 비밀값에 대해:

Secret Manager에서 **비밀 생성 (Create secret)**을 클릭하거나, 동일한 이름의 기존 비밀을 엽니다.
아래에 표시된 정확한 비밀 이름을 사용합니다.
값을 붙여넣거나 파일 내용을 업로드합니다.
저장하고 비밀값에 latest 버전이 생성되었는지 확인합니다.

부트스트랩 (bootstrap) 전 필수 항목:

Secret	값이 생성되는 곳	수행할 작업
`broccoli-oss-github-app-private-key-pem`	GitHub App 설정의 1단계에서 다운로드한 PEM 파일	PEM 전체 내용을 Secret 값으로 붙여넣기
...

이 README의 raw shell 경로를 따르는 경우, 수동으로 생성하는 것은 선택 사항입니다:

Secret	용도	가져오거나 생성하는 방법
`broccoli-oss-db-password`	`broccoli_oss` PostgreSQL 사용자의 비밀번호. 또한 Cloud SQL 배포를 위한 `broccoli-oss-database-url`을 도출하는 데 사용됨	로컬에서 무작위 값을 생성합니다 (예: `openssl rand -hex 32`)
...

broccoli-oss-gcp-deploy 헬퍼를 사용하는 경우, 프로젝트가 생성된 후 broccoli-oss-db-password, broccoli-oss-gh-webhook-secret, broccoli-oss-linear-webhook-secret를 자동으로 생성할 수 있습니다. 하지만 위에서 언급한 운영자 관리(operator-managed) Secret 4개는 여전히 직접 제공해야 합니다.

기본 Cloud SQL 경로의 경우:

broccoli-oss-database-url을 미리 채울 필요가 없습니다. deploy/bootstrap.sh가 Cloud SQL 연결 이름과 DB 비밀번호로부터 이를 도출한 다음, 해당 Secret을 자동으로 작성합니다.
broccoli-oss-db-password는 반드시 필요합니다. 이는 Cloud SQL 데이터베이스 사용자의 비밀번호이며, 무작위의 높은 엔트로피(high-entropy)를 가진 문자열이어야 합니다.

5. Cloud Build를 사용하여 이미지 빌드 및 푸시 (push)

cd path/to/this-repo
export GCP_PROJECT_ID=your-project
export GCP_REGION=us-central1
...

기본적으로 deploy/build-and-push.sh는 Google Cloud Build를 사용합니다. 이는 Google이 귀하의 GCP 프로젝트 내부에서 이미지를 빌드하고 푸시함을 의미하므로, 권장되는 배포 경로를 사용할 때 로컬 Docker가 필요하지 않습니다.

스크립트가 SERVICE_IMAGE=... 및 RUNNER_IMAGE=...를 출력하므로, 이를 복사하여 다음 단계에 사용할 수 있습니다.

만약 의도적으로 Docker를 사용하여 로컬에서 빌드하고 싶다면, 다음과 같이 설정하십시오:

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

6. 부트스트랩 (bootstrap) 실행

deploy/bootstrap.sh는 멱등성 (idempotent)을 가지며 Cloud Run의 환경 변수(env)/Secret의 증분 업데이트를 사용하므로, 안전하게 다시 실행할 수 있습니다.

기본적으로 배포 시 기존 Cloud Run Jobs 실행 경로(EXECUTION_BACKEND=cloud_run_jobs)를 유지합니다. Blaxel 샌드박스(sandboxes)를 사용하려면 서비스에 EXECUTION_BACKEND=blaxel을 설정하고, 서비스를 재시작하기 전에 아래의 선택적 Blaxel 환경 변수(env vars)들이 존재하는지 확인하십시오.

export GCP_PROJECT_ID=your-project
export GCP_REGION=us-central1
export GITHUB_APP_ID=123456
...

부트스트랩(Bootstrap) 출력 내용:

배포된 서비스 URL (service URL)
GitHub 웹훅 URL (GitHub webhook URL) (${Service URL}/webhooks/github)
Linear 웹훅 URL (Linear webhook URL) (${Service URL}/webhooks/linear)
Cloud Run 서비스 및 작업(job) 리소스 이름

DB_BACKEND=cloudsql인 경우, 부트스트랩은 Cloud SQL 인스턴스에 퍼블릭 IPv4를 패치하고 DB_AUTHORIZED_NETWORKS로부터 authorizedNetworks를 설정합니다. 기본값은 0.0.0.0/0이며, 이는 어디에서나 접속을 허용합니다. Postgres에 대한 직접적인 접근을 제한하려면 더 좁은 범위의 CIDR 목록으로 이를 재정의하십시오.

GitHub App 설정으로 돌아가서 홈페이지 URL (Homepage URL) 및 **웹훅 URL (Webhook URL)**을 위에 출력된 값으로 설정한 다음, broccoli-oss-gh-webhook-secret 값을 앱의 웹훅 비밀값(webhook secret) 필드에 붙여넣으십시오.

7. 리포지토리에 GitHub App 설치하기

GitHub App 설정에서:

Install App을 클릭합니다.
대상 리포지토리를 소유한 계정 또는 조직(org)을 선택합니다.
의도적으로 더 넓은 범위를 원하는 것이 아니라면 Only select repositories를 선택합니다.
대상 리포지토리에 대한 액세스 권한을 부여합니다.
설치 URL(/settings/installations/<id>)에서 **설치 ID (installation id)**를 캡처합니다. — 다음 단계에서 이를 시드(seed)로 사용하게 됩니다.

8. 마이그레이션 실행 및 리포지토리 설정 시딩

기본 Cloud Run + Cloud SQL 배포의 경우, broccoli-oss-database-url이 Cloud Run 런타임용으로 작성되며 /cloudsql/... Unix 소켓 경로를 사용합니다. 해당 비밀값(secret)은 배포된 서비스와 러너(runner)에는 올바르지만, 노트북에서 직접 사용하기에는 적절하지 않은 값입니다.

Show HN: Broccoli, 클라우드 기반의 원샷 코딩 에이전트

요약

핵심 포인트