실무에서 프로젝트 Git 운영 완벽 가이드

# 1. 브랜치 구조

main <- release <- develop <- feature/(예)로그인기능

 

# 2. 브랜치별 역할

main	실제 운영 서비스	release → main	Production	태그 기준 배포
release	QA / 검수 / 버그 수정	develop → release → main	Staging	코드 동결 후 QA
develop	통합 개발	feature/* → develop	Dev	신규 기능 통합
feature/*	개인 작업	develop에서 생성	로컬/Preview	기능 완료 후 PR

 

# 3. 운영규칙

3-1. 브랜치 네이밍

타입	예시	설명
기능	feature/login-page	신규 기능 개발
버그	fix/user-auth-error	QA 중 버그 수정
긴급	hotfix/payment-timeout	운영 긴급 대응

 

 

3-2. 커밋 컨벤션

• feat: 기능 추가
• fix: 버그 수정
• refactor: 코드 리팩토링
• docs: 문서 변경
• chore: 설정 변경
• test: 테스트 코드 추가

(예시)
feat: add user profile update API  
fix: resolve null token error on login

 

 

3-3. Merge 규칙

구분	방식	승인자	조건
feature → develop	PR	1명 이상	CI 통과
develop → release	PR	1명 이상	QA 완료
release → main	PR	팀장 승인	배포 전 최종 확인

 

 

3-4. 버전 및 태깅

변경유형	예시	설명
큰 구조 변경	v2.0.0	비호환 수정
기능 추가	v1.3.0	하위호환 유지
버그 수정	v1.3.1	기능 동일

(예시)
git tag -a v1.3.0 -m "Add profile update feature"
git push origin v1.3.0

 

 

3-5. 배포단계

단계 트리거 배포 대상

단계	트리거	배포 대상
feature/*	브랜치 push	Preview
develop	머지 시	Dev 서버
release	머지 시	Staging
main + tag	태그 push	Production

 

 

3-6. 협업 기본원칙

✅ main 직접 푸시 금지

✅ 모든 작업은 PR 리뷰 후 병합

✅ 작업 전 develop 최신 pull

✅ 완료 후 불필요한 브랜치 정리

# 1. 작업 시작
git checkout develop
git pull
git checkout -b feature/login-api

# 2. 커밋 & 푸시
git add .
git commit -m "feat: add login API"
git push -u origin feature/login-api

# 3. PR → develop

# 4. QA 완료 후 release 생성
git checkout develop && git pull
git checkout -b release/1.2.0
git push -u origin release/1.2.0

# 5. 배포
git checkout main && git merge release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin main --tags

 

 

 

실제 사용 예시

---

시나리오

• 개발자 A(민수)와 B(지영)가 로그인 기능을 함께 만듭니다.
• 우리 팀 브랜치 구조: feature/* → develop → release/* → main(+tag)

---

1) 각자 feature 브랜치에서 작업

민수

git checkout develop
git pull
git checkout -b feature/login-api   # 새 작업 브랜치 생성
# ... 코드 작업 ...
git add .
git commit -m "feat(login): add login API endpoint"
git push -u origin feature/login-api  # ← "현재 브랜치"로 push

지영

git checkout develop
git pull
git checkout -b feature/login-ui
# ... 코드 작업 ...
git add .
git commit -m "feat(login): build login form UI"
git push -u origin feature/login-ui

❗️왜 push가 main이 아니죠?

git push는 “지금 체크아웃한 브랜치(feature/….)”를 같은 이름의 원격 브랜치로 올립니다.

운영 보호를 위해 main은 직접 push 금지(보호 규칙)하고, PR로만 병합합니다.

---

2) 두 사람이 PR로 develop에 통합

민수 PR

• GitHub에서 feature/login-api → develop PR 생성
• CI 통과, 지영 리뷰 승인 → Merge

지영 PR

• feature/login-ui → develop PR 생성
• CI 통과, 민수 리뷰 승인 → Merge

이제 develop에 API + UI가 합쳐졌습니다.

(원한다면 자동으로 Dev 서버에 배포되도록 설정)

---

3) QA 시작을 위해 release 브랜치 생성

릴리즈 매니저(또는 팀장)가 수행:

git checkout develop
git pull
git checkout -b release/1.4.0      # 이번 배포 버전
git push -u origin release/1.4.0

• 이 순간부터 release/1.4.0은 코드 동결(새 기능 금지), QA/버그 수정만 허용
• Staging(검수 서버)에 자동 배포되도록 보통 CI/CD를 연결해둡니다.

QA 중 버그 발견 → release에서 바로 수정

# 민수가 버그 픽스
git checkout release/1.4.0
# ... 수정 ...
git add .
git commit -m "fix(login): handle empty email error"
git push

• Staging에 다시 자동 반영 → QA 통과될 때까지 반복

---

4) release → main 병합 + 태그로 배포

QA 통과 후, 릴리즈 매니저:

git checkout main
git pull
git merge --no-ff release/1.4.0 -m "merge: release/1.4.0 → main"
git push origin main

# 배포용 태그(프로덕션 트리거)
git tag -a v1.4.0 -m "Release v1.4.0: Login API & UI"
git push origin v1.4.0

• CI가 태그 푸시를 감지하여 프로덕션 배포 실행
• (선택) GitHub Releases에 릴리즈 노트 작성/자동화

---

5) release → develop 역병합(정리)

QA 중 release에서 고친 버그를 develop에도 반영해 다음 개발 라인과 이력을 맞춥니다.

git checkout develop
git pull
git merge --no-ff release/1.4.0 -m "merge: release/1.4.0 → develop"
git push

(원한다면 release/1.4.0 브랜치는 삭제)