Git 브랜치 전략 가이드
팀 프로젝트에서 Git을 효율적으로 운용하기 위한 브랜치 전략을 정리합니다. main과 develop을 중심으로 feature, release, hotfix 브랜치를 운용하는 방식입니다.
💡 참고
설명의 편의를 위해 도표나 설명에는 feature 키워드를 사용합니다. 실제 개발 시에는 120-feat-login, 121-refactor-auth와 같은 형태의 브랜치명을 활용합니다.
브랜치 흐름도
전체적인 브랜치 흐름은 다음과 같습니다. 각 브랜치가 어떻게 분기되고 병합되는지 시각적으로 확인할 수 있습니다.
Git 브랜치 흐름
main
v1.0.0
v1.0.1
release
develop
feature/a
feature/b
hotfix
브랜치 관계 요약
일반 개발
feature/*
↓ merge
develop
릴리즈
develop
↓ branch
release/*
↓ merge
main
긴급 수정
main
↓ branch
hotfix/*
↓ merge
main
브랜치 설명
| 브랜치 | 설명 | 배포 환경 | merge 대상 |
|---|---|---|---|
main |
Production 배포용. 언제나 안정적이고 배포 가능한 상태를 유지합니다. | 운영 서버 | release/*, hotfix/*에서 병합 |
develop |
코드 통합용. 다음 릴리즈를 위한 베이스캠프 역할을 합니다. | - | feature/*에서 병합 |
release/* |
QA 브랜치. 배포 전 QA를 진행합니다. | 개발 서버 | main, develop으로 병합 |
feature/* |
일반적인 개발 브랜치입니다. | - | develop으로 병합 |
hotfix/* |
Production 긴급 버그 수정용입니다. | - | main으로 병합 |
브랜치 보호 규칙
| 브랜치 | 보호 규칙 |
|---|---|
main |
PR 필수 (Direct Push 금지) |
release, develop |
CI 테스트 통과 필수 |
🏷️ 브랜치 명명 규칙
| 타입 | 구조 | 예시 |
|---|---|---|
| 기능 | <이슈번호>-feat-<이슈요약> |
302-feat-login |
| 릴리즈 | release/v<Major>.<Minor>.<Patch> |
release/v1.0.0, release/v2.1.3 |
| 핫픽스 | hotfix/<버전 또는 이슈> |
hotfix/v1.0.1, hotfix/security-patch |
⚠️ 중요
release 브랜치는 반드시 release/v<Major>.<Minor>.<Patch> 형식이어야 합니다. CI에서 브랜치 이름의 버전 형식과 기존 태그 대비 버전 유효성을 자동 검증합니다.
🔄 작업 워크플로우
1. 기능 개발 (Feature)
Feature 워크플로우
1
develop 브랜치 체크아웃
git checkout develop → git pull origin develop2
feature 브랜치 생성
git checkout -b feature/my-feature3
작업 수행 및 커밋
코드 작성 후 커밋을 진행합니다.
코드 작성 후 커밋을 진행합니다.
4
원격 저장소 푸시
git push origin feature/my-feature5
PR 생성 및 리뷰
feature → develop 방향으로 PR을 생성하고 리뷰 후 Squash Merge를 진행합니다.
feature → develop 방향으로 PR을 생성하고 리뷰 후 Squash Merge를 진행합니다.
# 1. develop 최신화 및 feature 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b feature/my-feature
# 2. 작업 수행 및 커밋
git add .
git commit -m "feat: 사용자 로그인 로직 추가"
# 3. 원격 저장소 푸시 및 PR 생성
git push origin feature/my-feature
# → GitHub/GitLab에서 develop 브랜치로 Pull Request 생성2. 릴리즈 (Release)
Release 워크플로우
1
release 브랜치 생성
develop에서
develop에서
git checkout -b release/v1.0.02
개발 서버 배포 및 QA
release 브랜치를 개발 서버에 배포하고 QA를 진행합니다.
release 브랜치를 개발 서버에 배포하고 QA를 진행합니다.
3
버그 수정 (필요시)
QA 중 발견된 버그는 release 브랜치에서 직접 수정합니다.
QA 중 발견된 버그는 release 브랜치에서 직접 수정합니다.
4
main으로 PR 생성 및 병합
리뷰 완료 후 main 브랜치에 병합합니다.
리뷰 완료 후 main 브랜치에 병합합니다.
5
CI 자동화
버전 범핑과 태그 생성이 자동으로 수행됩니다.
버전 범핑과 태그 생성이 자동으로 수행됩니다.
6
develop에 변경사항 반영
release 브랜치의 변경사항을 develop에도 반영합니다.
release 브랜치의 변경사항을 develop에도 반영합니다.
# 1. release 브랜치 생성 (반드시 v0.0.0 형식 준수)
git checkout develop
git pull origin develop
git checkout -b release/v1.0.0
# 2. release 브랜치 푸시 (개발 서버에 배포됨)
git push origin release/v1.0.0
# 3. QA 진행 - 버그 발견 시 해당 브랜치에서 수정
git commit -m "fix: QA에서 발견된 버그 수정"
git push origin release/v1.0.0
# 4. QA 완료 후 main으로 PR 생성 및 병합
# → GitHub/GitLab에서 main으로 PR 생성 → 리뷰 → Merge
# 5. develop에 변경사항 반영
git checkout develop
git merge release/v1.0.0
git push origin develop📌 참고
release 브랜치가 main에 병합되면 CI가 자동으로 버전 범핑과 태그 생성 그리고 패키지 배포를 수행합니다.
3. 핫픽스 (Hotfix)
Hotfix 워크플로우
1
main 기반 hotfix 브랜치 생성
git checkout -b hotfix/v1.0.12
긴급 수정 및 커밋
버그를 수정하고 커밋합니다.
버그를 수정하고 커밋합니다.
3
main 병합 및 태그
main에 병합하고 태그를 생성합니다.
main에 병합하고 태그를 생성합니다.
4
release 및 develop 반영
hotfix 내용을 release와 develop에도 반영합니다.
hotfix 내용을 release와 develop에도 반영합니다.
# 1. main 기반 hotfix 브랜치 생성
git checkout main
git pull origin main
git checkout -b hotfix/v1.0.1
# 2. 긴급 수정
git commit -m "fix: 심각한 보안 이슈 수정"
# 3. main 병합 및 태그
git checkout main
git merge hotfix/v1.0.1
git tag v1.0.1
git push origin main --tags
# 4. release에도 반영
git checkout release/v1.0.1
git merge main
git push origin release/v1.0.1
# 5. develop에도 반영
git checkout develop
git merge release/v1.0.1
git push origin develop커밋 메시지 컨벤션
형식
<type>(<scope>): <subject>
<body>Type 종류
| Type | 설명 | 버전 영향 |
|---|---|---|
feat |
새로운 기능 추가 | Minor |
improve |
기존 기능 개선/수정 (동작 변경 포함) | Minor |
fix |
버그 수정 | Patch |
docs |
문서 수정 | - |
style |
코드 포맷팅 (로직 변경 없음) | - |
refactor |
코드 리팩토링 (기능 변경 없음) | Patch |
perf |
성능 개선 | Patch |
test |
테스트 코드 추가/수정 | - |
chore |
빌드 업무 및 패키지 매니저 설정 등 | - |
feat vs improve vs refactor
세 가지 타입이 헷갈릴 수 있어 정리합니다.
| Type | 사용 시점 | 예시 |
|---|---|---|
feat |
없던 기능을 새로 만들 때 | 다크모드 기능 추가 |
improve |
있던 기능을 개선/변경할 때 | 버튼 클릭 피드백 개선 |
refactor |
동작은 그대로이고 코드만 정리할 때 | 함수 분리 및 변수명 변경 |
예시
feat(auth): 구글 소셜 로그인 추가
improve(button): 버튼 클릭 시 ripple 효과 개선
fix(modal): 모달 닫기 버튼 정렬 수정
refactor(utils): 날짜 포맷 함수 분리
chore(deps): 패키지 의존성 업데이트Breaking Change
호환성이 깨지는 변경은 커밋 타입 뒤에 !를 붙이거나 footer에 BREAKING CHANGE:를 명시합니다.
feat!: API 응답 형식 변경
BREAKING CHANGE: 기존 { data: [] } 형식에서 { items: [], total: number } 형식으로 변경'je개발 회고' 카테고리의 다른 글
| [ CI/CD ] 모노레포 Gitlab CI/CD 전략 (0) | 2025.12.22 |
|---|---|
| [ 번들러 ] 모노레포 번들러 비교 (0) | 2025.12.22 |
| [ 번들러 ] Monorepo 모노레포 번들러 비교 (0) | 2025.12.16 |
| [ 데이터 품질 관리 ] (4) Frontend : Batching (4) | 2025.08.19 |
| [ 데이터 품질 관리 ] (3) Frontend : Zod 스키마와 API 검증 (3) | 2025.08.18 |