# [[GitHub Flow]]

## 📌 Brief Summary
GitHub Flow는 복잡한 Git Flow의 대안으로 사용되는 가볍고 단순한 브랜치 기반 워크플로우입니다 [1, 2]. 이 방식은 항상 배포 가능한 상태(deployable)를 유지하는 `main` 브랜치를 중심으로 작동하며, 개발자는 새로운 작업을 위해 짧은 주기의 기능 브랜치(feature branch)를 생성합니다 [3-5]. 변경된 코드는 동료의 코드 리뷰와 CI/CD 테스트를 모두 통과한 후 오직 Pull Request(PR)를 통해서만 `main`에 병합됩니다 [1, 6].

## 📖 Core Content
* **안정적인 `main` 브랜치 유지**
  GitHub Flow의 핵심은 `main` (또는 `master`) 브랜치가 항상 안정적이고 언제든 배포 가능한 상태여야 한다는 점입니다 [3-5]. 개발자는 어떠한 경우에도 `main` 브랜치에 직접 커밋(direct commit)해서는 안 됩니다 [1, 6, 7].
* **기능 브랜치(Feature Branch) 기반 작업**
  모든 새로운 기능 개발, 버그 수정, 문서 작업 등은 `main`에서 파생된 짧은 수명(short-lived)의 전용 브랜치에서 수행되어야 합니다 [3-5]. 브랜치 이름은 `feature/user-auth` 또는 `bugfix/login-error`와 같이 설명적이어야 하며, 가능하면 티켓 ID(예: `PROJ-123`)를 포함하여 추적성을 높이는 것이 좋습니다 [8, 9].
* **Pull Request (PR) 및 코드 리뷰**
  작업이 완료되면 `main` 브랜치로 병합하기 위해 PR을 생성합니다 [6, 10]. 병합 전에는 반드시 최소 1명 이상의 팀원에게 코드 리뷰(Peer Review)를 받아야 하며, CI/CD 환경에서의 자동화 테스트를 통과해야 합니다 [1, 6, 8]. 이는 혼자서 잘못된 코드를 병합하는 것을 방지하는 안전장치입니다 [8].
* **병합 규칙과 정리**
  커밋 히스토리를 깔끔하게 유지하기 위해 PR을 병합할 때는 'Squash Merge' 방식을 주로 사용합니다 [6, 7, 11]. 성공적으로 병합된 이후에는 불필요한 브랜치가 쌓이지 않도록 기능 브랜치를 즉시 삭제(auto-delete)합니다 [6, 8, 11].
* **워크플로우 마이그레이션 (Migration)**
  팀이 기존의 복잡한 Git Flow에서 GitHub Flow로 전환하여 통합 속도를 높이고 단순화하려면, 릴리스 브랜치(release branch) 생성을 중단하고, `develop` 브랜치를 `main`으로 통합한 뒤, `main` 브랜치에서 직접 배포하도록 CI/CD 파이프라인을 업데이트해야 합니다 [2]. 반대로 프로젝트의 구조가 더 복잡해지면 `develop` 브랜치 등을 추가해 Git Flow로 되돌아갈 수도 있습니다 [12].

## ⚖️ Trade-offs & Caveats
* **병합 코드의 즉각적인 리스크**: `main` 브랜치가 유일한 배포 기준점이 되므로, 리뷰나 테스트가 누락되어 버그가 포함된 코드가 병합될 경우 프로덕션(운영) 환경에 치명적인 영향을 미칠 수 있습니다 [13, 14]. 따라서 강력한 CI/CD 자동화 환경과 Branch Protection Rule(보호 규칙)이 필수적으로 뒷받침되어야 합니다 [1, 6].
* **브랜치 수명 관리의 어려움**: 기능 브랜치가 너무 오래 유지(Long-lived)되면 `main` 브랜치와의 차이가 벌어져 심각한 병합 충돌(Merge Conflict)이 발생합니다 [13, 15]. 이를 방지하기 위해 개발자는 매일 작업 전 `main` 브랜치의 최신 상태를 당겨오고(pull/rebase) 변경 사항을 작게 유지하는 규율을 엄격히 지켜야 합니다 [11, 13].
* **대규모/정기 릴리스 프로젝트에서의 한계**: 정해진 일정에 따라 버전을 묶어서 배포해야 하거나, 유지보수해야 할 과거 릴리스 버전이 여러 개인 대규모 프로젝트의 경우, 릴리스 브랜치가 없는 GitHub Flow는 구조적 한계를 가집니다. 이 경우에는 무겁더라도 Git Flow가 더 적합할 수 있습니다 [12, 16].

## 🔗 Knowledge Connections

### Related Concepts

#### [관계 유형 A: 아키텍처/기반 기술 (개발 워크플로우)]
- [[Git Flow]]
  - 연결 이유: GitHub Flow와 자주 비교되는 분기 전략으로, 프로젝트의 복잡성에 따라 두 전략 사이를 마이그레이션하는 경우가 많습니다 [2, 12].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: `develop`, `release`, `hotfix` 브랜치를 사용하는 Git Flow를 이해함으로써, 상대적으로 GitHub Flow가 생략한 구조적 복잡성과 그에 따른 속도/단순성의 이점을 명확히 비교할 수 있습니다.
- [[Trunk-Based Development]]
  - 연결 이유: 소규모 팀에서 빠르고 충돌 없는 병합을 위해 도입할 수 있는 또 다른 경량 워크플로우입니다 [3, 16].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 극단적으로 짧은 생명주기의 브랜치를 사용하거나 메인에 빈번히 직접 병합하는 철학을 통해 CI(지속적 통합)의 본질을 더 깊게 이해할 수 있습니다.

#### [관계 유형 B: 구현/활용 도구]
- [[Pull Request]]
  - 연결 이유: GitHub Flow에서 코드 병합을 수행하고 팀원 간의 협업 및 리뷰를 진행하는 가장 핵심적인 메커니즘입니다 [8, 10].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 코드 품질 통제, 피어 리뷰(Peer Review)의 역할 및 CI/CD 훅(Hook)이 작동하는 방식을 구체적으로 이해할 수 있습니다.
- [[CI/CD]]
  - 연결 이유: `main` 브랜치를 항상 배포 가능한 상태로 유지하기 위해 배후에서 코드를 검증하는 필수 자동화 파이프라인입니다 [1, 6].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 왜 수동 병합이 위험한지, PR 리뷰가 끝난 코드가 어떻게 안전하게 프로덕션 레벨까지 배포되는지의 전 과정을 파악할 수 있습니다.

### Deeper Research Questions
- Git Flow 기반 프로젝트에서 GitHub Flow로 마이그레이션할 때, 기존의 버전 관리 체계 및 배포 자동화 파이프라인을 어떻게 재설계해야 하는가?
- GitHub Flow 환경에서 기능이 미완성된 상태로 `main`에 병합되어야 할 때, Feature Flag(기능 토글)를 어떻게 효과적으로 활용할 수 있는가?
- 팀 규모가 3~5인에서 20인 이상으로 급격히 성장할 때, GitHub Flow의 한계점은 구체적으로 어떻게 나타나며 어떤 시점에 워크플로우를 전환해야 하는가?
- 커밋 히스토리를 정리하기 위해 권장되는 Squash Merge 방식이 장기적인 버그 추적성(Traceability) 관점에서는 어떤 단점을 가질 수 있는가?
- Branch Protection을 통해 '최소 1인의 리뷰'와 'CI 통과'를 강제할 때, 코드 리뷰 병목 현상을 해결하기 위한 프로세스적 최적화 방법은 무엇인가?

### Practical Application Contexts
- **Implementation:** 개발자는 JIRA 등에서 할당받은 티켓 ID를 기반으로 `feature/PROJ-123-login` 형식의 브랜치를 따고, 한 가지 논리적 변경사항만 담은 Atomic Commit을 수행한 뒤 PR을 생성합니다.
- **System Design:** GitHub/GitLab 등의 레포지토리 설정에서 `main` 브랜치에 대해 직접 푸시(Direct Push)를 차단하고, Status Check(테스트 통과) 및 지정된 리뷰어의 Approve를 강제하는 보호 규칙(Branch Protection)을 설계합니다.
- **Operation / Maintenance:** CI/CD 파이프라인이 `main` 브랜치의 변경을 감지하면 자동으로 프로덕션에 배포되도록 구성하고, 저장소의 깔끔한 관리를 위해 병합된 브랜치는 시스템에서 자동 삭제되도록 설정합니다.
- **Learning Path:** Git 브랜치 기초 명령어 숙지 -> 1기능 1브랜치 원칙 실습 -> PR 작성 및 동료 리뷰 경험 -> 자동화된 CI/CD와의 연동 이해의 순서로 협업 능력을 성장시킬 수 있습니다.
- **My Project Relevance:** 3~5명의 소규모 팀에서 충돌을 최소화하면서도 빠른 피드백과 릴리스가 필요한 현재 프로젝트 상황에, 불필요한 절차를 없애고 안정성을 보장하는 가장 이상적인 협업 모델로 적용할 수 있습니다.

### Adjacent Topics
- [[Conventional Commits]]
  - 확장 방향: 커밋 메시지를 `feat:`, `fix:`, `chore:` 등의 규격으로 통일함으로써, PR 내용의 가독성을 높이고 향후 릴리스 노트를 자동화하는 방향으로 지식을 확장할 수 있습니다.
- [[Issue Tracking System]]
  - 확장 방향: 코드 구현(GitHub)과 요구사항 정의(JIRA, Linear 등)를 연결하여 프로젝트 관리 수준을 높이고 변경 사항의 비즈니스 맥락(Traceability)을 추적하는 방법론으로 확장됩니다.

---
*Last updated: 2026-04-30*