GitHub Branch Protection 완전 정리 – 실무 브랜치 전략과 품질 게이트 설계 방법

1. 왜 브랜치 보호가 필요한가?

Git에서 브랜치는 단순한 코드 분기점이 아닙니다.
특히 main 또는 dev 는 프로덕션 품질 기준선입니다.

하지만 다음과 같은 문제가 자주 발생합니다:

• 직접 push로 코드 품질 저하
• 테스트 미통과 상태로 머지
• 충돌 상태 방치
• 리뷰 없이 병합

이를 막기 위한 기능이 바로
GitHub Branch Protection입니다.

---

2. Branch Protection이란?

GitHub에서 특정 브랜치에 대해:

• 직접 push 금지
• PR 필수화
• CI 통과 강제
• 리뷰 승인 필수
• force push 차단

등을 설정하는 기능입니다.

경로:

 

Repository → Settings → Branches → Add rule

 

---

3. 주요 설정 항목 설명

1️⃣ Require a pull request before merging

• 직접 push 금지
• PR 통해서만 병합 가능
• 리뷰 프로세스 강제

👉 실무에서는 거의 필수

---

2️⃣ Require status checks to pass

CI가 통과해야 머지 가능

예:

• Backend - Build/Test
• SonarCloud Scan
• Lint Check

품질 게이트 역할을 합니다.

---

3️⃣ Require branches to be up to date

머지 전 최신 main과 rebase/merge 필요

→ 오래된 브랜치에서 병합 방지

---

4️⃣ Require review from code owners

CODEOWNERS 파일 기반 승인 필수

대기업/엔터프라이즈에서 사용

---

5️⃣ Block force pushes

히스토리 변조 방지

---

4. 브랜치 전략 유형 비교

📌 1) GitHub Flow

가장 단순한 전략

 

main
└─ feature/*

 

특징:

• 항상 main이 배포 가능 상태
• PR 기반 개발
• CI 중심

✔ 스타트업, 소규모 팀에 적합

---

📌 2) Git Flow

 

main
develop
feature/*
release/*
hotfix/*

 

특징:

• 역할 분리 명확
• 릴리즈 단위 관리
• 복잡도 높음

✔ 대규모 프로젝트, 배포 주기 긴 경우

---

📌 3) Trunk-Based Development

 

main (trunk)
└─ short-lived branch

 

특징:

• 브랜치 수명 매우 짧음
• CI/CD 자동화 중심
• 기능 토글 활용

✔ DevOps 조직에 적합

---

5. 실무 추천 브랜치 전략 (Spring Boot + CI 기준)

르무엘님 같은 백엔드 중심 프로젝트 기준으로 추천:

 

main → 운영 기준선
develop → 통합 테스트 브랜치
feature/* → 기능 단위
hotfix/* → 긴급 수정

 

---

6. 권장 Branch Protection 설정 예시

🎯 main 브랜치

✔ Require pull request
✔ Require status checks
✔ Require branch up to date
✔ Block force push

Required Checks:

• Backend - Build/Test
• SonarCloud
• Lint

---

🎯 develop 브랜치

✔ Require pull request
✔ Require status checks
❌ 리뷰 필수는 선택

---

7. 모노레포에서의 보호 전략

모노레포 + path filter 구조라면

문제:

• backend만 변경했는데 frontend 체크가 Required면 머지 불가
• skip된 job은 Required 충족 안 됨

해결:

✔ 항상 실행되는 공통 job 1개 Required
✔ 조건부 job은 Optional

---

8. Branch 전략과 CI 설계의 연결

브랜치 전략은 CI와 함께 설계해야 합니다.

예시:

 

feature/*
↓ PR
CI 실행
↓
품질 통과
↓
develop 머지
↓
통합 테스트
↓
main 머지
↓
Docker build & push

 

---

9. 흔한 실수

❌ 모든 체크를 Required로 설정
❌ 조건부 job을 Required로 설정
❌ main에 직접 push 허용
❌ 리뷰 없이 merge 허용

---

10. 결론

Branch Protection은

“코드 저장소를 통제하는 기능”이 아니라
“품질을 자동으로 강제하는 정책 도구”

입니다.

브랜치 전략 + CI + 품질 도구(Sonar, Qodana 등)와 함께 설계해야 합니다.

---

🔥 정리

항목필수 여부

PR 필수	✔
CI 통과	✔
Force push 차단	✔
리뷰 승인	팀 규모에 따라