본문으로 건너뛰기

Git Workflows · EP 02

GitHub Flow - 빠르고 단순한 Git 워크플로우

GitHub Flow는 빠른 배포와 간단한 협업을 위한 Git 브랜치 전략입니다. 복잡한 브랜치 구조 없이 하루에도 여러 번 안전하게 배포할 수 있는 단순하고 강력한 워크플로우를 알아봅니다.

· 15분 읽기
share

개요

GitHub Flow는 빠른 배포와 간단한 협업을 위한 Git 브랜치 전략입니다. 이 가이드를 통해 GitHub Flow의 핵심 원리를 이해하고, 실제 프로젝트에서 어떻게 활용하는지 배울 수 있습니다.

GitHub Flow를 사용하면:

  • 복잡한 브랜치 구조 없이 간단하게 협업할 수 있습니다
  • 하루에도 여러 번 안전하게 배포할 수 있습니다
  • Pull Request를 통해 효과적으로 코드 리뷰를 진행할 수 있습니다

배경

왜 GitHub Flow가 필요한가?

전통적인 Git Flow는 체계적이고 안정적이지만, 복잡한 브랜치 구조 때문에 다음과 같은 문제가 발생합니다:

  1. 복잡한 브랜치 관리: main, develop, feature, release, hotfix 등 5가지 종류의 브랜치를 관리해야 합니다
  2. 느린 배포 주기: release 브랜치를 거쳐야 하므로 배포까지 시간이 오래 걸립니다
  3. 높은 학습 곡선: 새로운 팀원이 워크플로우를 익히는 데 시간이 필요합니다

GitHub는 이러한 문제를 해결하기 위해 하루에도 여러 번 배포하는 환경에 최적화된 워크플로우를 개발했습니다. GitHub 내부에서는 하루에 수십 번 배포가 일어나며, 작은 변경사항도 빠르게 프로덕션에 반영됩니다.

Git Flow와의 차이점

Git Flow (복잡한 버전 관리)

master ─────────────────────────────> (프로덕션)
    ↑                              ↑
develop ───────┬──────────────────┘
               ↑
          feature/login
          feature/payment
          ...

GitHub Flow (단순한 지속적 배포)

main ─────────────────────────────────> (항상 배포 가능)
    ↓                             ↗
  feature/add-login ──────────────┘
  feature/fix-bug ────────────────┘

GitHub Flow의 핵심 원칙

원칙 1: main 브랜치는 항상 배포 가능해야 한다

main 브랜치는 절대적으로 안정적이어야 합니다. main에 있는 코드는 언제든지 프로덕션에 배포할 수 있어야 합니다.

# ✅ main 브랜치는 항상 이 상태여야 합니다
- 모든 테스트 통과
- 빌드 성공
- 실제 프로덕션에서 동작 가능

원칙 2: 새로운 작업은 main에서 브랜치를 만든다

모든 기능 개발, 버그 수정, 실험은 main에서 분기한 새로운 브랜치에서 진행합니다.

# main에서 새 브랜치 생성
git checkout main
git pull origin main
git checkout -b feature/add-user-profile

원칙 3: 브랜치 이름은 설명적이어야 한다

브랜치 이름만 보고도 어떤 작업을 하는지 알 수 있어야 합니다.

# ✅ 좋은 브랜치 이름
feature/add-login-button
fix/memory-leak-in-dashboard
experiment/new-search-algorithm
hotfix/security-vulnerability

# ❌ 나쁜 브랜치 이름
test
my-branch
feature1
temp

원칙 4: Pull Request를 통해 피드백을 받는다

코드를 main에 병합하기 전에 반드시 Pull Request(PR)를 생성하고 팀원들의 리뷰를 받습니다.

원칙 5: 리뷰가 승인되면 즉시 병합하고 배포한다

PR이 승인되면 main에 병합하고, 바로 프로덕션에 배포합니다.


GitHub Flow 6단계 실습

1단계: 브랜치 생성

먼저 main 브랜치를 최신 상태로 업데이트한 후, 새 브랜치를 생성합니다.

# 1. main 브랜치로 이동
git checkout main

# 2. 원격 저장소의 최신 내용을 가져오기
git pull origin main

# 3. 새 기능 브랜치 생성 및 이동
git checkout -b feature/add-dark-mode

결과: feature/add-dark-mode 브랜치가 생성되고, 현재 작업 브랜치가 변경됩니다.

# 현재 브랜치 확인
git branch
# 출력:
# * feature/add-dark-mode
#   main

2단계: 코드 작성 및 커밋

브랜치에서 작업을 진행하고 의미 있는 단위로 커밋합니다.

# 1. 파일 수정 (예: 다크 모드 CSS 추가)
# src/styles/dark-mode.css 파일 생성

# 2. 변경사항 확인
git status

# 3. 변경된 파일 스테이징
git add src/styles/dark-mode.css

# 4. 커밋 (명확한 메시지 작성)
git commit -m "feat: Add dark mode CSS styles"

커밋 메시지 작성 팁:

# ✅ 좋은 커밋 메시지
feat: Add user authentication feature
fix: Resolve memory leak in dashboard
docs: Update API documentation
refactor: Simplify user validation logic

# ❌ 나쁜 커밋 메시지
update
fix bug
changes
WIP

작업 중 여러 번 커밋하기:

# 첫 번째 작업
git add src/styles/dark-mode.css
git commit -m "feat: Add dark mode base styles"

# 두 번째 작업
git add src/components/ThemeToggle.tsx
git commit -m "feat: Add theme toggle component"

# 세 번째 작업
git add src/hooks/useDarkMode.ts
git commit -m "feat: Add dark mode custom hook"

3단계: 원격 저장소에 푸시

작업한 브랜치를 원격 저장소에 푸시합니다.

# 처음 푸시하는 경우 (브랜치 생성과 함께)
git push -u origin feature/add-dark-mode

# 이후 푸시하는 경우
git push

결과: GitHub 저장소에 새 브랜치가 생성되고, 커밋 내역이 업로드됩니다.

4단계: Pull Request 생성

GitHub 웹 인터페이스에서 Pull Request를 생성합니다.

GitHub에서 PR 생성하기:

  1. GitHub 저장소 페이지 접속
  2. “Compare & pull request” 버튼 클릭 (푸시 직후 자동으로 표시됨)
  3. PR 제목과 설명 작성

PR 템플릿 예시:

## 변경 사항
- 다크 모드 CSS 스타일 추가
- 테마 토글 컴포넌트 구현
- useDarkMode 커스텀 훅 생성

## 테스트
- [ ] 라이트 모드에서 다크 모드로 전환 확인
- [ ] 로컬 스토리지에 테마 설정 저장 확인
- [ ] 새로고침 후 테마 유지 확인

## 스크린샷
[다크 모드 스크린샷 첨부]

## 관련 이슈
Closes #123

5단계: 코드 리뷰 및 논의

팀원들이 PR을 검토하고 피드백을 제공합니다.

리뷰어가 확인할 사항:

  • 코드 품질과 가독성
  • 테스트 커버리지
  • 성능 및 보안 이슈
  • 프로젝트 컨벤션 준수

리뷰 피드백 반영하기:

# 1. 피드백에 따라 코드 수정
# 파일 수정...

# 2. 수정사항 커밋
git add .
git commit -m "refactor: Apply code review feedback"

# 3. 다시 푸시 (같은 PR에 자동으로 반영됨)
git push

리뷰 중 대화 예시:

리뷰어: "다크 모드 토글 버튼의 접근성을 개선할 수 있을까요?"
작성자: "좋은 지적입니다. aria-label을 추가하겠습니다."

리뷰어: "테마 변경 시 깜빡임이 발생하는데, 트랜지션을 추가하면 어떨까요?"
작성자: "CSS transition을 추가해서 부드럽게 전환되도록 개선했습니다."

6단계: 병합 및 배포

모든 리뷰가 승인되고 테스트가 통과하면 main에 병합합니다.

GitHub에서 병합하기:

  1. PR 페이지에서 “Merge pull request” 버튼 클릭

  2. 병합 방식 선택:

    • Merge commit: 모든 커밋 내역 유지
    • Squash and merge: 여러 커밋을 하나로 합침 (권장)
    • Rebase and merge: 커밋 히스토리를 선형으로 유지
  3. “Confirm merge” 클릭

명령줄에서 병합하기 (선택사항):

# 1. main 브랜치로 이동
git checkout main

# 2. 최신 상태로 업데이트
git pull origin main

# 3. feature 브랜치 병합
git merge feature/add-dark-mode

# 4. 원격 저장소에 푸시
git push origin main

# 5. 로컬 feature 브랜치 삭제
git branch -d feature/add-dark-mode

# 6. 원격 feature 브랜치 삭제
git push origin --delete feature/add-dark-mode

배포:

# 자동 배포 설정이 되어 있다면
# main 브랜치에 병합되면 자동으로 배포됩니다

# 수동 배포의 경우
git checkout main
git pull origin main
npm run deploy

실전 시나리오

시나리오 1: 긴급 버그 수정 (Hotfix)

프로덕션에서 버그가 발견되었을 때:

# 1. 최신 main에서 hotfix 브랜치 생성
git checkout main
git pull origin main
git checkout -b hotfix/fix-login-error

# 2. 버그 수정 및 커밋
# 파일 수정...
git add .
git commit -m "fix: Resolve login authentication error"

# 3. 푸시
git push -u origin hotfix/fix-login-error

# 4. PR 생성하고 빠르게 리뷰 받기
# GitHub에서 PR 생성...

# 5. 승인되면 즉시 병합 및 배포
# GitHub에서 Merge...

핵심: GitHub Flow에서는 hotfix도 일반 기능 개발과 동일한 프로세스를 따릅니다. 단지 더 빠르게 진행될 뿐입니다.

시나리오 2: 실험적 기능 개발

새로운 아이디어를 테스트할 때:

# 1. 실험용 브랜치 생성
git checkout main
git pull origin main
git checkout -b experiment/new-search-algorithm

# 2. 실험 진행
# 코드 작성 및 테스트...
git add .
git commit -m "experiment: Try new search algorithm"
git push -u origin experiment/new-search-algorithm

# 3. 실험 결과가 좋으면 PR 생성
# 실험 결과가 좋지 않으면 브랜치 삭제
git checkout main
git branch -D experiment/new-search-algorithm
git push origin --delete experiment/new-search-algorithm

시나리오 3: 충돌 해결

여러 사람이 동시에 작업할 때 충돌이 발생할 수 있습니다:

# 1. 작업 중 main이 업데이트된 경우
git checkout feature/add-dark-mode

# 2. main의 최신 변경사항 가져오기
git fetch origin main

# 3. 현재 브랜치에 main 병합
git merge origin/main

# 4. 충돌 발생 시
# 충돌 파일 수정...
git add .
git commit -m "merge: Resolve conflicts with main"

# 5. 푸시
git push

충돌 해결 예시:

// 충돌이 발생한 파일
<<<<<<< HEAD
const theme = 'dark';
=======
const theme = 'light';
>>>>>>> origin/main

// 해결 후
const theme = localStorage.getItem('theme') || 'light';

팀 협업 Best Practices

1. 브랜치 네이밍 컨벤션

팀 내에서 일관된 브랜치 이름 규칙을 사용합니다:

# 기능 개발
feature/add-user-authentication
feature/implement-payment-system

# 버그 수정
fix/resolve-memory-leak
fix/correct-date-formatting

# 문서 작업
docs/update-api-documentation
docs/add-deployment-guide

# 리팩토링
refactor/simplify-auth-logic
refactor/optimize-database-queries

# 실험
experiment/test-new-ui
experiment/try-different-algorithm

# 긴급 수정
hotfix/security-patch
hotfix/critical-bug-fix

2. 작은 단위로 자주 커밋

# ✅ 좋은 습관: 작은 단위로 여러 번 커밋
git commit -m "feat: Add login button component"
git commit -m "feat: Add login form validation"
git commit -m "feat: Implement login API integration"

# ❌ 나쁜 습관: 모든 작업을 한 번에 커밋
git commit -m "feat: Add entire login feature"

3. PR 크기 관리

이상적인 PR 크기:

  • 변경된 파일: 5~10개 이하
  • 변경된 라인: 200~400 라인 이하
  • 리뷰 시간: 15~30분 이내
# 큰 기능을 작은 PR로 나누기
feature/user-profile
├── feature/user-profile-ui       (UI 컴포넌트만)
├── feature/user-profile-api      (API 연동만)
└── feature/user-profile-tests    (테스트만)

4. 명확한 PR 설명 작성

PR 템플릿:

## 목적
이 PR의 목적을 간단히 설명합니다.

## 변경 사항
- 변경 사항 1
- 변경 사항 2
- 변경 사항 3

## 테스트 방법
1. 단계 1
2. 단계 2
3. 예상 결과

## 체크리스트
- [ ] 테스트 코드 작성
- [ ] 문서 업데이트
- [ ] 코드 스타일 가이드 준수
- [ ] 성능 영향 검토

## 스크린샷 (UI 변경 시)
[스크린샷 첨부]

## 관련 이슈
Closes #123
Related to #456

5. 브랜치 보호 규칙 설정

GitHub에서 main 브랜치를 보호합니다:

  1. Settings > Branches > Branch protection rules
  2. 다음 규칙 활성화:
    • ✅ Require a pull request before merging
    • ✅ Require approvals (1~2명)
    • ✅ Require status checks to pass
    • ✅ Require conversation resolution before merging
    • ✅ Do not allow bypassing the above settings
# .github/workflows/ci.yml
# 자동 테스트 설정 예시
name: CI

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
      - name: Run linter
        run: npm run lint

GitHub Flow vs Git Flow 비교

브랜치 구조

Git Flow:

master (프로덕션)
  ↑
develop (개발)
  ↑
feature/* (기능 개발)
release/* (릴리스 준비)
hotfix/* (긴급 수정)

GitHub Flow:

main (프로덕션 + 개발)
  ↑
feature/* (모든 작업)

배포 주기

특성Git FlowGitHub Flow
배포 빈도주/월 단위일/시간 단위
배포 방식계획된 릴리스지속적 배포
Hotfix별도 브랜치일반 브랜치와 동일

팀 규모별 적합성

Git Flow가 적합한 경우:

  • 대규모 팀 (10명 이상)
  • 정기 릴리스 주기가 있는 프로젝트
  • 여러 버전을 동시에 지원해야 하는 경우
  • 엔터프라이즈 환경

GitHub Flow가 적합한 경우:

  • 소규모중규모 팀 (210명)
  • 빠른 배포가 필요한 프로젝트
  • 웹 서비스, SaaS 제품
  • 스타트업 환경

복잡도 비교

Git Flow:

# 평균 명령어 수: 15~20개
git checkout develop
git pull origin develop
git checkout -b feature/new-feature
# 작업...
git checkout develop
git merge feature/new-feature
git checkout -b release/1.0.0
# 테스트...
git checkout master
git merge release/1.0.0
git tag v1.0.0
git checkout develop
git merge master

GitHub Flow:

# 평균 명령어 수: 6~8개
git checkout main
git pull origin main
git checkout -b feature/new-feature
# 작업...
git push -u origin feature/new-feature
# GitHub에서 PR 생성 및 병합

장점과 한계

장점

1. 간단하고 배우기 쉽다

# 핵심 워크플로우가 단순합니다
1. 브랜치 생성 → 2. 작업 → 3. PR → 4. 병합 → 5. 배포
  • 새로운 팀원이 빠르게 적응할 수 있습니다
  • Git 초보자도 쉽게 이해할 수 있습니다
  • 복잡한 브랜치 전략을 외울 필요가 없습니다

2. 빠른 배포가 가능하다

# 변경사항이 즉시 프로덕션에 반영됩니다
feature → PR → merge → deploy (1~2시간 이내)

# Git Flow는 여러 단계를 거칩니다
feature → develop → release → master → deploy (며칠~주 단위)

3. CI/CD와 자연스럽게 통합된다

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: npm run deploy

4. 코드 리뷰가 필수화된다

  • 모든 변경사항이 PR을 통해 이루어집니다
  • 자연스럽게 코드 품질이 향상됩니다
  • 팀원들이 서로의 코드를 이해할 수 있습니다

한계

1. 버전 관리가 어렵다

# ❌ GitHub Flow는 명시적인 버전이 없습니다
main: commit1 → commit2 → commit3 → ...

# ✅ Git Flow는 명확한 버전이 있습니다
master: v1.0.0 → v1.1.0 → v2.0.0

해결 방법:

# Git 태그를 사용하여 버전 관리
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

2. 프로덕션 이슈 대응이 복잡할 수 있다

# 문제 상황: main에 버그가 있는 커밋이 있고,
# 이미 다른 기능들이 병합되어 있을 때

main: [good] → [bug] → [feature1] → [feature2]

해결 방법:

# Revert 커밋을 사용
git revert <buggy-commit-hash>

# 또는 새로운 수정 커밋 추가
git checkout -b hotfix/fix-critical-bug
# 수정...
# PR 생성 및 빠르게 병합

3. 대규모 팀에서는 충돌이 자주 발생한다

# 10명 이상이 동시에 main에 병합하면
# 충돌 해결에 많은 시간이 소요됩니다

해결 방법:

# 작업 시작 전 main을 자주 업데이트
git checkout feature/my-feature
git fetch origin main
git rebase origin/main

# 작은 단위로 자주 병합
# 하루에 여러 개의 작은 PR을 병합

4. 여러 환경을 동시에 유지하기 어렵다

# ❌ GitHub Flow는 단일 환경(프로덕션)에 최적화
main → production

# Git Flow는 여러 환경을 지원
master → production
develop → staging
feature → development

해결 방법:

# 환경별 브랜치 추가 (Modified GitHub Flow)
main → production
staging → staging environment
develop → development environment

Modified GitHub Flow (변형 전략)

순수 GitHub Flow가 적합하지 않은 경우, 다음과 같이 변형할 수 있습니다:

1. Staging 브랜치 추가

main      (프로덕션)
  ↑
staging   (스테이징 환경)
  ↑
feature/* (기능 개발)

워크플로우:

# 1. feature 브랜치에서 작업
git checkout -b feature/new-feature

# 2. staging에 병합하여 테스트
git checkout staging
git merge feature/new-feature
git push origin staging
# 스테이징 환경에서 테스트...

# 3. 테스트 통과 후 main에 병합
git checkout main
git merge feature/new-feature
git push origin main
# 프로덕션 배포...

2. Release 태그 사용

# 주기적으로 릴리스 태그 생성
git checkout main
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0

# 릴리스 노트 자동 생성
git log v1.1.0..v1.2.0 --oneline > RELEASE_NOTES.md

3. Feature Flag 활용

// 완료되지 않은 기능도 main에 병합
// 하지만 Feature Flag로 숨김

const FEATURES = {
  NEW_UI: process.env.FEATURE_NEW_UI === 'true',
  PAYMENT_V2: process.env.FEATURE_PAYMENT_V2 === 'true'
};

function App() {
  return (
    <>
      {FEATURES.NEW_UI ? <NewUI /> : <OldUI />}
      {FEATURES.PAYMENT_V2 && <PaymentV2 />}
    </>
  );
}

자주 묻는 질문 (FAQ)

Q1. main 브랜치에 실수로 잘못된 코드가 병합되었을 때 어떻게 하나요?

A1. Revert 커밋을 사용합니다:

# 1. 잘못된 커밋의 해시 확인
git log --oneline

# 2. Revert 커밋 생성
git revert <commit-hash>

# 3. 푸시
git push origin main

# Revert는 기존 커밋을 유지하면서 변경사항을 되돌립니다
# 따라서 안전하고 추적 가능합니다

Q2. 여러 개의 기능을 동시에 개발하고 있는데, 순서대로 병합해야 하나요?

A2. 아니요, 독립적으로 병합할 수 있습니다:

# 기능들이 서로 영향을 주지 않는다면
# 준비된 순서대로 병합하면 됩니다

feature/add-user-profile → main (월요일)
feature/add-payment      → main (화요일)
feature/add-search       → main (수요일)

# 기능들이 서로 의존한다면
# 의존성을 고려하여 순서대로 병합합니다

Q3. PR이 오래 방치되면 어떻게 하나요?

A3. 정기적으로 main의 변경사항을 반영합니다:

# 1. 최신 main 가져오기
git checkout feature/my-feature
git fetch origin main

# 2. main의 변경사항 병합
git merge origin/main

# 또는 rebase 사용 (커밋 히스토리가 깔끔함)
git rebase origin/main

# 3. 충돌 해결 후 푸시
git push --force-with-lease origin feature/my-feature

Q4. main 브랜치에서 직접 커밋해도 되나요?

A4. 절대 안 됩니다:

# ❌ 절대 하지 말 것
git checkout main
git add .
git commit -m "Quick fix"
git push origin main

# ✅ 항상 브랜치를 만들어서 작업
git checkout -b hotfix/quick-fix
git add .
git commit -m "Quick fix"
git push -u origin hotfix/quick-fix
# PR 생성...

이유:

  • 코드 리뷰를 거치지 않으면 품질 문제가 발생할 수 있습니다
  • 다른 팀원들이 변경사항을 모를 수 있습니다
  • CI/CD 테스트를 건너뛰게 됩니다

Q5. 브랜치를 병합한 후에는 어떻게 하나요?

A5. 로컬과 원격 브랜치를 모두 삭제합니다:

# 1. GitHub에서 PR 병합 시 자동 삭제 옵션 체크
# "Delete branch" 버튼 클릭

# 2. 로컬에서 브랜치 삭제
git checkout main
git pull origin main
git branch -d feature/my-feature

# 3. 원격 브랜치가 남아있다면 삭제
git push origin --delete feature/my-feature

# 4. 오래된 원격 브랜치 참조 정리
git fetch --prune

정리

GitHub Flow는 단순함과 속도를 추구하는 Git 워크플로우입니다:

핵심 기억할 점

  1. main 브랜치는 항상 배포 가능해야 합니다
  2. 모든 작업은 설명적인 이름의 브랜치에서 진행합니다
  3. Pull Request를 통해 코드 리뷰를 받습니다
  4. 리뷰가 승인되면 즉시 병합하고 배포합니다

언제 사용하나요?

✅ 빠른 배포가 필요한 웹 서비스 ✅ 소규모중규모 팀 (210명) ✅ 지속적 배포(CD) 환경 ✅ 스타트업, 애자일 개발

언제 사용하지 않나요?

❌ 정기 릴리스 주기가 있는 제품 ❌ 대규모 팀 (10명 이상) ❌ 여러 버전 동시 지원 ❌ 엔터프라이즈 환경

GitHub Flow를 사용하면 복잡한 브랜치 관리 없이도 효율적으로 협업할 수 있습니다. 작게 시작해서 팀의 필요에 맞게 점진적으로 개선해나가세요!


참고 자료

공식 문서

추가 학습 자료

한국어 자료


버전: 1.0.0 작성일: 2026-01-16 언어: 한국어 (Korean) 기반 자료: GitHub 공식 문서

Related

· 16 min read Git Workflows

GitLab Flow 이해하기

GitLab Flow는 Git Flow의 체계성과 GitHub Flow의 단순성을 결합한 Git 브랜치 전략입니다. main 브랜치 중심 개발과 환경별 브랜치로 안전한 배포 프로세스를 구현하는 방법을 알아봅니다.

GitCI/CD
→
· 18 min read Git Workflows

Trunk-based Development 이해하기

Trunk-based Development는 모든 개발자가 하나의 메인 브랜치에서 작업하고 짧은 생명주기의 피처 브랜치만 사용하는 소스 코드 관리 방식입니다. CI/CD를 위한 필수 전제조건과 실전 적용 방법을 알아봅니다.

GitCI/CD
→
· 17 min read Git Workflows

Git Flow 워크플로우 완벽 가이드

Git Flow는 Vincent Driessen이 2010년에 제안한 브랜치 관리 전략으로, 체계적인 소프트웨어 버전 관리와 출시를 위해 설계되었습니다. 이 워크플로우는 5가지 브랜치 타입을 활용하여 기능 개발, 출시 준비, 긴급 버그 수정을 명확하게 분리합니다.

GitCI/CD
→