Allra Fintech
Convention

Git Flow 컨벤션

Allra 프로젝트의 Git 브랜치 전략 및 워크플로우

Git Flow 컨벤션

Allra 프로젝트에서 사용하는 Git 브랜치 전략과 워크플로우에 대한 가이드입니다.

📋 목차

브랜치 구조

브랜치 타입

1. Main Branches

main (운영 브랜치)

  • 목적: 프로덕션 배포용 브랜치 ( 운영계와 연결, 수동 배포 필요 )
  • 특징:
    • 모든 기능이 최종적으로 병합되는 브랜치
    • 병합 즉시 프로덕션 환경에 배포
    • 항상 안정적인 상태 유지
  • 병합 소스: develop

develop (기본 브랜치)

  • 목적: 개발 통합 브랜치
  • 특징:
    • 개발 중인 코드가 모이는 브랜치
    • 기능이 안정화되면 main 브랜치로 병합 ( rebase 방식 )
    • 일일 개발 작업의 기준점
  • 병합 소스: feature/*, fix/*, refactor/*, hotfix/*, e2e/*, qa/*

2. Supporting Branches (보조 브랜치)

feat/* - 기능 개발

  • 분기: develop
  • 병합: develop
  • 명명 규칙: feat/[기능명] 또는 feat/[이슈번호]
  • 예시:
    • feat/login-page
    • feat/646 (이슈 번호)
    • feat/impersonation

fix/* - 버그 수정

  • 분기: develop
  • 병합: develop
  • 명명 규칙: fix/[버그명] 또는 fix/[이슈번호]
  • 예시:
    • fix/2(이슈 번호)
    • fix/pdf-viewer-error(버그명)

refactor/* - 코드 리팩토링

  • 분기: develop
  • 병합: develop
  • 명명 규칙: refactor/[목적] 또는 refactor/[이슈번호]
  • 특징:
    • 기존 기능에 영향을 주지 않는 코드 개선
    • 코드 구조 정리 및 최적화
    • 작은 단위로 나누어 작업 (충돌 방지)
  • 예시:
    • refactor/cleanup-auth-module
    • refactor/optimize-performance
    • refactor/644

e2e/* - E2E 테스트

  • 분기: develop
  • 병합: develop
  • 명명 규칙: e2e/[이슈번호] 또는 e2e/[테스트명]
  • 특징: End-to-End 테스트 작성 및 개선 ( 테스트 케이스 추가 )
  • 예시:
    • e2e/663
    • e2e/contract-flow

qa/* - QA 테스트

  • 분기: develop
  • 병합: develop
  • 특징: QA 환경 테스트용 브랜치 ( 개발계와 연결, 자동 배포 )
  • 예시:
    • qa/1(이슈 번호)
    • qa/login-page(테스트명)

hotfix/* - 긴급 수정

  • 분기: develop, main
  • 병합: develop, main ( 이후 즉시 main 브랜치 혹은 develop 브랜치와 동기화 필요 )
  • 명명 규칙: hotfix/[이슈명] 또는 hotfix/[이슈번호]
  • 특징: 프로덕션 긴급 버그 수정용
  • 예시:
    • hotfix/security-patch
    • hotfix/3(이슈 번호)

⚠️ Hotfix 주의사항:

  1. 보통 develop 브랜치에서 분기하고 수정 완료 후 develop에 먼저 병합
  2. 반드시 main에도 즉시 병합 (동기화, 수동 배포 필요)
  3. 경우에 따라 cherry-pick 방식으로 main에는 hotfix 브랜치에서 커밋한 내용만 병합되도록 필요할 수 있음 ( develop 브랜치에서 아직 작업 중이지만 운영계에 넣으면 안되는 작업이 있는 경우 )

워크플로우

기본 개발 플로우

1. 기능 개발 시작

# develop 브랜치 최신화
git checkout develop
git pull origin develop

# 새 기능 브랜치 생성
git checkout -b feat/646

# 개발 진행...
git add .
git commit -m "✨ 사업자번호 검증 후 상호명 입력 처리 로직 구현"

# 원격 저장소에 Push
git push origin feat/646

추가로, cursor의 commands기능을 사용하여 자동으로 commit 메시지를 생성하고 있습니다. 그래서 좀 더 실무적인 과정은 다음과 같아요.

# develop 브랜치 최신화
git checkout develop
git pull origin develop

# 새 기능 브랜치 생성
git checkout -b feat/646

# cursor tab에서 /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋

# 만약 올바르지 않은 커밋이 들어갔다면 직접 입력
git reset --mixed HEAD~1
git commit -m "✨ 사업자번호 검증 후 상호명 입력 처리 로직 구현"

# 원격 저장소에 Push
git push origin feat/646

2. Pull Request 생성 및 병합

  1. GitHub에서 Pull Request 생성
  2. 코드 리뷰 진행 ( coderabbitai의 자동 코드 리뷰 혹은 직접 리뷰 )
  3. 리뷰 승인 후 develop 브랜치에 병합
  4. 로컬 브랜치 삭제
# 원격 저장소에서 PR 생성

# 로컬 브랜치 삭제
git branch -d feat/646

commit과 마찬가지로 cursor의 commands기능을 사용하여 자동으로 PR 생성을 진행하고 있습니다.

# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성

# 원격 저장소에서 PR 검증 후 수정

# 로컬 브랜치 삭제
git branch -d feature/login-page

3. 긴급 수정 플로우 (Hotfix)

프로세스 상으로는 위 사진이고 실제 코드로 치면 다음과 같아요.

# develop에서 hotfix 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b hotfix/3

# 긴급 수정 및 커밋
git add .
git commit -m "🔒 보안 취약점 패치"

# 원격 저장소에 Push
git push origin hotfix/3

# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정
# Squash & Merge 방식으로 병합

# develop에 병합
git checkout develop
git pull origin develop

# main에 병합
git checkout main
git rebase develop
git push origin main

hotfix 이전

hotfix 이후

만약 develop 브랜치에서 아직 main 브랜치로 들어가면 안되는 작업이 있다면 다음과 같이 작업할 수 있어요. ( 노션 기준, 메인 브랜치에 먼저 병합되고 나서 develop 브랜치에 병합하는 경우 )

4. 릴리즈 플로우

# develop이 안정화되면 main으로 병합
git checkout main
git pull origin main
git rebase develop
git push origin main

커밋 메시지 컨벤션

기본 형식

[이모지 타입] 커밋 메시지 (#PR번호)

커밋 타입

이모지타입설명예시
Feature새로운 기능 추가[✨ Feature] 진행중인 계약 중복 체크 기능 추가 (#651)
🐛Fix버그 수정[🐛 Fix] PDF 뷰어 에러 바운더리 추가 (#656)
♻️Refactor코드 리팩토링[♻️ Refactor] DateRangePicker 공통 컴포넌트화 (#662)
💄DesignUI/UX 개선[💄 DESIGN Q/A] 자동선정산 신청 모달 UI/UX 개선 (#654)
🔧Config설정 변경[🔧 Config] 스토리북 mock 설정 개선 (#661)
📝Docs문서 작업[📝 Docs] README 문서 개선 및 프로젝트 정보 추가 (#643)
🚀Release릴리즈[🚀 Release] 상품마진 고도화 2차 배포 (#638)
Test테스트 추가/수정[✅ Test] E2E 테스트 케이스 추가
⚡️Perf성능 개선[⚡️ Perf] 이미지 로딩 최적화
🔒Security보안 이슈 수정[🔒 Security] XSS 취약점 패치

개별 커밋 메시지 (PR 전)

PR로 병합되기 전 개별 커밋은 간결한 형식을 사용합니다:

이모지 커밋 메시지

예시:

  • ✨ 로그인 페이지 UI 구현
  • 🐛 버튼 클릭 이벤트 버그 수정
  • ♻️ 계약 유형 관리 로직 리팩토링 및 에러 처리 개선
  • ✨ 계약 플로우 네비게이션 차단 기능 완성

: GitHub 이모지 코드(, 🐛 등)를 사용해도 됩니다.

실제 프로젝트 커밋 예시

# PR 병합 커밋 (Squash & Merge)
[♻️ Refactor] DateRangePicker 공통 컴포넌트화 및 중복 코드 대폭 제거 (#662)
[🐛 Fix] 남은 한도 음수 처리 방어 로직 추가 (#665)
[✨ Feature] 진행중인 계약 중복 체크 기능 추가 (#651)

# 개별 커밋
♻️ 계약 유형 관리 로직 리팩토링 에러 처리 개선
 계약 플로우 네비게이션 차단 기능 완성 E2E 테스트 추가
🐛 계약 완료 네비게이션 차단 해제 타이밍 이슈 수정

로컬 브랜치 관리

브랜치 최신화

# 정기적으로 develop 브랜치 최신화
git checkout develop
git pull origin develop

# 작업 중인 브랜치에 최신 변경사항 반영
git checkout feat/my-feature
git rebase develop

충돌 최소화 팁

  1. 작은 단위로 자주 커밋: 큰 변경사항을 한 번에 커밋하지 않기
  2. 정기적으로 최신화: 하루에 한 번 이상 develop 브랜치와 동기화
  3. 빠른 병합: PR을 오래 열어두지 않고 빠르게 병합
  4. 작은 PR: 한 번에 너무 많은 변경사항을 포함하지 않기

불필요한 브랜치 정리

# 로컬 브랜치 목록 확인
git branch

# 병합된 브랜치 삭제
git branch -d feature/old-feature

# 강제 삭제 (병합되지 않은 브랜치)
git branch -D feature/abandoned-feature

# 원격에서 삭제된 브랜치 로컬에서 제거
git fetch --prune

실전 예시

Case 1: 새로운 기능 개발

# 1. 이슈 확인: #646 - 사업자번호 검증 기능 추가

# 2. 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b feat/646

# 3. 개발 및 커밋
git add .
git commit -m "✨ 사업자번호 검증 후 상호명 입력 처리 로직 구현" # /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋

# 4. Push 및 PR
git push origin feat/646
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정

# 5. 코드 리뷰 후 병합
# Squash & Merge 방식으로 병합

# 6. 로컬 정리
git checkout develop
git pull origin develop
git branch -d feature/646

# 운영계 반영
git checkout main
git rebase develop
git push origin main
# argoCD 수동 배포 후 확인

Case 2: 리팩토링 작업

# 1. 이슈 확인: #662 - DateRangePicker 공통 컴포넌트화

# 2. 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b refactor/662

# 3. 리팩토링 작업 (작은 단위로 커밋)
git add src/components/DateRangePicker
git commit -m "♻️ DateRangePicker 공통 컴포넌트 추출" # /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋

git add src/pages
git commit -m "♻️ 중복 코드 제거 및 공통 컴포넌트 적용" # /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋

# 4. Push 및 PR
git push origin refactor/662
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정

# 5. 코드 리뷰 후 병합
# Squash & Merge 방식으로 병합

# 6. 로컬 정리
git checkout develop
git pull origin develop
git branch -d refactor/662

# 운영계 반영
git checkout main
git rebase develop
git push origin main
# argoCD 수동 배포 후 확인

Case 3: 긴급 수정

# 1. 프로덕션 버그 발견: PDF 뷰어 에러

# 2. develop에서 hotfix 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b hotfix/3

# 3. 긴급 수정
git add .
git commit -m "🐛 PDF 뷰어 Promise.withResolvers 폴리필 추가" # /commit 명령어 입령하여 자동으로 커밋 메시지를 생성하고 커밋

# 4. Push 및 PR
git push origin hotfix/3
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정

# 5. 코드 리뷰 후 병합
# Squash & Merge 방식으로 병합

# 6. 로컬 정리
git checkout develop
git pull origin develop
git branch -d hotfix/3

# 운영계 반영
git checkout main
git rebase develop
git push origin main
# argoCD 수동 배포 후 확인

베스트 프랙티스

✅ DO

  • PR 병합 시 Squash & Merge 사용
  • 커밋 메시지에 이모지와 타입 명시
  • PR 제목에 이슈 번호 포함
  • 작은 단위로 자주 커밋하고 병합
  • 코드 리뷰는 신속하게 진행
  • hotfix 병합 후 반드시 develop에도 rebase 필요
  • 브랜치 이름은 명확하고 간결하게

❌ DON'T

  • main 브랜치에 직접 Push 금지, 대신 develop 브랜치에서 rebase 후 Push 필요
  • 리뷰 없이 병합 금지
  • 오래된 브랜치 방치 금지
  • 너무 큰 PR 생성 금지 (500줄 이상)
  • 커밋 메시지 대충 작성 금지
  • hotfixdevelop 동기화 누락 금지, rebase 필요

참고 자료