GitLab App

Sophonz GitLab App을 프로젝트에 설치하면 실제 사용자 에러 데이터를 분석해 자동으로 이슈를 생성하고 코드 수정 MR을 제안합니다.

동작 원리

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

Sophonz ──MCP──▶ AI Agent ──브랜치 + 커밋──▶ GitLab 프로젝트
                     │
                     └──────────▶ Merge Request ──▶ 개발자

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

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

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

사전 요구 사항

sophonz-gitlab는 GitLab.com 및 self-hosted GitLab 인스턴스를 지원합니다. 연동에는 Group 또는 Project Access Token이 필요합니다.

설치

1단계: Access Token 발급

GitLab 그룹 또는 프로젝트에서 Access Token을 발급합니다.

• Group Access Token: 그룹 → Settings → Access Tokens
• Project Access Token: 프로젝트 → Settings → Access Tokens

필요한 스코프: api, read_repository, write_repository

발급된 토큰은 안전한 곳에 보관하세요. 화면을 벗어나면 다시 확인할 수 없습니다.

2단계: Sophonz 콘솔에서 연동 설정

Sophonz 콘솔의 연동 → GitLab App 메뉴에서 다음 정보를 입력합니다.

• GitLab 인스턴스 URL (기본값: https://gitlab.com)
• 발급한 Access Token
• 연동 대상 그룹 ID 또는 프로젝트 경로

3단계: 온보딩 MR 생성

설정 완료 후 Sophonz 콘솔 또는 API로 온보딩 MR을 트리거합니다. MR은 프로젝트 루트에 .sophonz/config.yml을 추가합니다.

단일 프로젝트 온보딩:

curl -X POST "https://your-sophonz-instance/gitlab/onboard" \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId": 12345, "projectPath": "your-org/your-repo"}'

그룹 일괄 온보딩:

curl -X POST "https://your-sophonz-instance/gitlab/onboard/group/9999" \
  -H "Authorization: Bearer $SERVICE_TOKEN"

응답 상태: config-already-present / branch-exists / pr-created / skipped-error

4단계: 서비스 연결 설정

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

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

service.key는 GitLab 프로젝트의 CI/CD 변수(Settings → CI/CD → Variables)에 저장한 뒤 ${{ secrets.SOPHONZ_SERVICE_KEY }}로 참조합니다. 키를 파일에 직접 커밋하지 마세요.

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

필요 권한 (Access Token 스코프)

GitHub ↔ GitLab 개념 매핑

Merge Request 구성

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

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

1-shot 수동 실행

스케줄을 기다리지 않고 즉시 단일 에러 시그니처를 처리하려면:

curl -X POST "https://your-sophonz-instance/sophonz/agent-run" \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId": 12345, "projectPath": "your-org/your-repo", "forceDryRun": true}'

signature 필드를 지정하면 해당 시그니처만 처리합니다. 미지정 시 상위 에러 1건을 처리합니다.

데이터 처리

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