GitHub App

Sophonz GitHub App을 리포지토리에 설치하면 실제 사용자 에러 데이터를 분석해 자동으로 이슈를 생성하고 코드 수정 PR을 제안합니다.

동작 원리

sophonz-github는 Sophonz MCP를 통해 런타임 에러 데이터를 가져와 AI 에이전트가 패치 브랜치를 생성하고 Pull Request를 엽니다.

Sophonz ──MCP──▶ AI Agent ──브랜치 + 커밋──▶ GitHub 리포
                     │
                     └──────────▶ Pull Request ──▶ 개발자

.sophonz/config.yml에 정의된 스케줄에 따라 다음 과정을 반복합니다.

1. Sophonz에서 설정된 시간 윈도우의 상위 에러 조회
2. 스택 프레임을 리포지토리 내 파일로 매핑
3. Claude 기반 AI 에이전트로 패치 초안 작성
4. 에러 시그니처별로 그룹화하여 Pull Request 생성

자세한 AI Agent 파이프라인 개요는 AI Agent 개요를 참고하세요.

설치

1단계: App 설치

GitHub 마켓플레이스 또는 Sophonz 콘솔의 연동 → GitHub App 메뉴에서 sophonz-github를 대상 조직 또는 리포지토리에 설치합니다.

2단계: 온보딩 PR 승인

설치 직후 App이 리포지토리 루트에 .sophonz/config.yml을 추가하는 온보딩 Pull Request를 자동으로 생성합니다. 내용을 확인한 뒤 머지하세요.

3단계: 서비스 연결 설정

온보딩 PR에서 또는 이후 별도 PR로 .sophonz/config.yml의 서비스 정보를 채웁니다.

service:
  namespace: "<sophonz-service-namespace>"
  name: "<sophonz-service-name>"
  key: "${{ secrets.SOPHONZ_SERVICE_KEY }}"  # 리포지토리 Secret 참조
 
schedule: "every weekday before 9am"  # 또는 cron, 예: "0 0 * * 1-5"
window: "24h"
topN: 10
 
ai:
  model: "claude-sonnet-4-6"
  maxIterations: 4
 
pr:
  branchPrefix: "sophonz/"
  labels: ["sophonz", "bug"]
  draft: false
  groupBySignature: true
 
scope:
  allowedPaths: ["src/**", "apps/**"]
  blockedPaths: ["**/node_modules/**", "**/dist/**"]
 
triggers:
  schedule: true
  workflowFailure: true
  manualComment: true

service.key는 GitHub 리포지토리 Secret(Settings → Secrets and variables → Actions)에 저장한 뒤 ${{ secrets.SOPHONZ_SERVICE_KEY }}로 참조합니다. 키를 파일에 직접 커밋하지 마세요.

설정 파일을 머지하면 정의된 스케줄부터 자동 실행됩니다.

필요 권한

App 설치 시 다음 권한을 요청합니다.

구독 이벤트: Workflow run, Pull request, Push, Issue comment

Pull Request 구성

생성된 PR에는 다음 정보가 포함됩니다.

• 에러 메시지 및 가장 많이 영향받은 서비스 버전
• 발생 횟수 및 세션 수
• 마지막 발생 시각
• 매핑된 스택 프레임
• 관련 트레이스 ID (Sophonz 대시보드 링크 포함)
• AI 에이전트의 수정 근거 요약

슬래시 커맨드

PR 코멘트에서 다음 커맨드를 사용할 수 있습니다.

데이터 처리

• service.key는 런타임에 리포지토리 Secret에서 읽어 Sophonz MCP 호출에만 사용하며, 저장하지 않습니다.
• 리포지토리 코드는 패치 생성 시점에만 LLM에 전달되며, 모델 학습에 사용되지 않습니다 (Anthropic API 정책).
• 에러 데이터와 코드는 Sophonz 워크스페이스와 패치 생성에 사용된 LLM 공급자 외부로 전송되지 않습니다.