David Brain

4-1_Git-Webhook-연동

3 min read

ID: key_26_22_05_25_P4_4_1 Created date: 5월 25 2026 월요일

연관 문서

개발 일정 > Phase 4 서버 개발 | DB 설계

개요

GitHub / GitLab Webhook을 수신하여 커밋·PR 정보를 이슈와 연동한다.
스마트 커밋으로 이슈 상태 자동 전환을 지원한다.

  • 예상 소요: 4~5일
  • 선행 조건: Phase 2~3 완료

Claude Code 작업 수행서

작업 지시

CIRA 서버에 Git Webhook 연동 기능을 구현해줘.

[지원 플랫폼]
- GitHub (우선), GitLab (추후)

[수행 작업]

1. DB 마이그레이션
   V200__create_git_integration.sql:
   git_repositories: id(UUID), project_id(FK), repo_name, repo_url,
                     provider(ENUM: GITHUB/GITLAB), webhook_secret, access_token_encrypted
   git_commits: id(UUID), repository_id(FK), commit_hash(VARCHAR 40), message(TEXT),
                author_name, author_email, commit_date(TIMESTAMPTZ), linked_issue_id(FK→issues)
   git_pull_requests: id(UUID), repository_id(FK), pr_number(INT), title,
                      status(VARCHAR 50 — OPEN/MERGED/CLOSED), branch_name,
                      linked_issue_id(FK→issues), merged_at(TIMESTAMPTZ)

2. Webhook 수신 엔드포인트
   POST /api/v1/webhooks/github
   - 인증: X-Hub-Signature-256 검증 (HMAC-SHA256)
   - 처리 이벤트: push, pull_request
   - 허용 목록: /webhooks/** 는 인증 필터 제외

3. Push 이벤트 처리 (커밋)
   - 커밋 메시지에서 이슈 키 파싱: 정규식 [A-Z]+-\d+ (예: CIRA-123)
   - 스마트 커밋 명령어 파싱:
     * CIRA-123 #comment 수정 완료   → 이슈에 댓글 자동 추가
     * CIRA-123 #in-progress          → 이슈 상태 "In Progress" 변경
     * CIRA-123 #resolve               → 이슈 상태 "Done" 변경
   - git_commits 테이블 INSERT
   - linked_issue_id 설정
   - 이슈 상세 페이지에 "연결된 커밋" 섹션 데이터 제공

4. PR 이벤트 처리
   - PR 제목 / 브랜치명에서 이슈 키 파싱
     예: feature/CIRA-123-add-login → CIRA-123 추출
   - PR opened  → 이슈에 "PR 연결됨" 댓글 + 링크
   - PR merged  → 이슈 상태 자동 "Done" 전이 (설정 가능)
   - PR closed  → 알림만

5. Git 저장소 연결 API
   POST /api/v1/projects/{projectId}/git-repositories
   - repo_url, provider, access_token 등록
   - webhook_secret 생성 (랜덤 256-bit) → 반환
   - 사용자가 GitHub Webhook 설정에 입력

6. 이슈 연결 커밋/PR 조회 API
   GET /api/v1/issues/{issueId}/git-activity
   Response: { commits: [...], pullRequests: [...] }

[보안 주의]
- access_token_encrypted: AES-256 암호화 후 저장
- webhook_secret: HMAC 검증에만 사용, 응답에 노출 금지

완료 기준

항목기준
Webhook 수신GitHub 서명 검증 통과
이슈 키 파싱커밋 메시지에서 CIRA-123 추출
스마트 커밋resolve 시 이슈 상태 자동 변경
PR 연동PR merge 시 이슈 Done 처리
Git 활동 조회이슈 상세에 커밋/PR 표시

Graph View