¶ 3권 — GitHub 기반으로 개발하기: 형상관리 첫걸음
이 책은 "돈을 많이 들이지 않고 개발 환경의 뼈대를 갖추는" 2부의 한 축으로, 코드를 안전하게 보관하고 여러 사람이 하나의 코드베이스를 사고 없이 함께 다룰 수 있게 하는 형상관리 체계를 GitHub을 기준으로 정리한다.
이 책부터 시리즈 전체를 관통하는 가상 예시 프로젝트 TodoBox(Next.js+Vercel+Supabase 기반 할 일 관리 서비스)가 본격적으로 등장해 이후 여러 권에서 계속 이어진다.
¶ GitHub 요금제 체계와 무료로 쓸 수 있는 범위
GitHub 도입의 첫 판단은 "우리 규모에서 무료로 어디까지 가능한가"이다.
GitHub 요금제는 Free / Pro / Team / Enterprise Cloud / Enterprise Server 다섯 단계로 나뉜다. 실무적으로 중요한 사실은 Private 저장소 개수와 협업자 수에는 애초에 제한이 없고, GitHub Actions만 플랜별로 월 사용 시간이 다르다는 점이다.
| 플랜 | GitHub Actions 월 사용 시간 |
|---|---|
| Free | 2,000분 |
| Team | 3,000분 |
| Enterprise | 50,000분 |
즉 "몇 명까지 무료냐"는 질문 자체가 성립하지 않는다.
유료 전환이 필요해지는 신호는 인원 수가 아니라 다음 네 가지에서 온다.
- 팀 단위 권한 관리
- 필수 리뷰어·브랜치 보호 강제
- CI 사용량 초과
- SAML SSO 같은 보안·컴플라이언스 요구
¶ GitLab 소개와 GitHub 비교
GitHub만 놓고 판단하기 전에 대안인 GitLab을 함께 이해해야 "왜 이걸 골랐는지" 설명할 수 있다.
GitLab은 계획-코드-빌드-테스트-배포-모니터링을 하나의 애플리케이션으로 설계 초기부터 통합한 플랫폼이다. GitHub이 저장소·PR 중심에서 출발해 Actions를 후발로 얹은 것과는 결이 다르다.
두 서비스의 가장 뚜렷한 차이는 완전 무료 셀프호스팅 가능 여부다.
| 항목 | GitHub | GitLab |
|---|---|---|
| 셀프호스팅 | 유료 Enterprise Server 라이선스 필요 | Community Edition으로 무료(이슈 트래커·CI/CD 포함) |
이 시리즈는 다음 두 가지 이유로 SaaS 조합(GitHub)을 기본으로 삼는다.
- 초기 스타트업 대부분이 셀프호스팅 여력이 없다.
- GitHub의 방대한 Marketplace 생태계가 자동화 조립에 유리하다.
다만 조직이 커져 보안·비용 문제로 자체 구축이 필요해지는 시점을 대비해 6부에서 GitLab 기반 자체 구축을 별도로 다룬다.
¶ Git과 GitHub의 관계, 그리고 저장소 초기 설정
Git이 이력 관리 "엔진"이라면 GitHub은 이슈·PR·리뷰·자동화를 얹은 "플랫폼"이다.
형상관리 없이 코드를 주고받으면 팀원이 2~3명만 넘어도 다음 문제가 나타난다.
- 변경 추적 불가
- 동시 수정 덮어쓰기
- 롤백 불가
- 신규 입사자의 맥락 파악 불가
판단 기준은 명확하다. 코드가 "되돌릴 가치가 있는 것"이라면 1인 개발이라도 그 시점부터 Git/GitHub을 써야 한다.
저장소를 처음 만들 때는 다음 항목을 가볍게 표준화해두는 것으로 충분하다.
- Public/Private 여부(기본은 Private)
- README
.gitignore- 기본 브랜치 이름(
main)
¶ 브랜치 전략: 무엇을 고를 것인가
브랜치 전략은 업계에서 정리되어 온 세 흐름으로 나뉜다.
| 전략 | 특징 | 적합한 상황 |
|---|---|---|
| Git Flow | 여러 장기 브랜치(develop/release/hotfix)를 릴리스 주기에 맞춰 운용 | 온프레미스 납품·패키지 소프트웨어처럼 여러 버전을 동시에 유지해야 하는 프로젝트 |
| GitHub Flow | 기본 브랜치를 항상 배포 가능한 상태로 유지하며 기능마다 짧은 브랜치를 PR로 병합·즉시 배포 | 지속 배포하는 웹 서비스 |
| Trunk-based Development | 하루 한 번 이상 트렁크에 통합하고 미완성 기능은 기능 플래그로 숨김 | 탄탄한 자동화 테스트가 갖춰진 프로젝트 |
핵심 판단 축은 하나다. "우리는 몇 개의 버전을 동시에 유지해야 하는가?" 답이 "하나"에 가까우면 GitHub Flow·Trunk-based 쪽이, "여러 개"에 가까우면 Gitflow 쪽이 유리하다.
이 책은 스타트업 기본값으로 GitHub Flow를 권장하고, 온프레미스 납품이나 앱스토어 심사처럼 사업적 이유가 생겼을 때만 release/hotfix 요소를 더하라고 조언한다.
아울러 기본 브랜치에는 "직접 푸시 금지, PR을 통해서만 병합"하는 보호된 브랜치 설정을 첫 번째 안전장치로 둘 것을 권장한다.
¶ PR·코드리뷰 워크플로 설계
Pull Request는 코드가 반영되기 전 리뷰어와 논의하는 공간으로, 다음 세 가지 가치를 갖는다.
- 버그를 조기에 잡는다.
- 특정 라인 단위로 피드백을 남긴다.
- 무엇이 왜 바뀌었는지 이력을 남긴다.
이를 뒷받침하는 장치는 다음과 같다.
- PR 템플릿(
.github/pull_request_template.md)으로 "무엇을/왜/어떻게 테스트했는지/관련 이슈"를 강제한다. CODEOWNERS파일로 코드베이스 영역별 리뷰어를 자동 지정한다.- 브랜치 보호 규칙으로 승인 인원수·최근 푸시자 재승인 금지·CI 상태 검사 통과를 병합 조건으로 강제한다.
소규모 팀 최소 권장안은 다음과 같다.
- PR을 통해서만 병합
- 최소 1인 이상 승인(본인 코드 셀프승인 금지)
- CI 통과 필수
여기에 라벨 체계(bug, needs review, blocked 등)를 더하면 PR·이슈 상태가 한눈에 가시화된다.
¶ 팀 권한 관리
팀이 3~4명을 넘으면 전원이 관리자 권한인 상태 자체가 리스크가 된다.
GitHub 조직 단위의 Member/Owner/Billing manager/Security manager 역할을 최소 권한 원칙에 따라 나눠야 한다.
- 조직 Owner는 대표·CTO 1~2인으로 최소화한다.
- 일반 개발자는 소속 팀에 필요한 저장소만 Write 권한을 준다.
- 외부 협력자는 Outside collaborator로 한정하고 종료 시 즉시 회수한다.
- 결제 권한은 개발 권한과 분리한다.
인원이 늘수록 "권한을 준 뒤 회수를 잊는" 문제가 커지므로 분기별 점검 루틴이 필요하다.
¶ GitHub Actions로 무엇까지 할 수 있는가
GitHub Actions는 다음 네 단계 구조로 이뤄진다.
- workflow: YAML로 정의되는 자동화 단위
- job: 병렬/순차 실행 가능한 작업 단위
- step: 명령 실행 또는 Marketplace 액션 재사용
- runner: 실행 서버
실무에서 흔히 구현하는 범위는 다음과 같이 폭넓다.
- CI(테스트·린트 자동 실행)
- CD(스테이징·프로덕션 자동 배포)
- 이슈·PR 자동화
- 스케줄 작업
- 서드파티 연동
- 보안 자동화
이 책이 권장하는 시작 범위는 "PR을 열면 테스트·린트가 자동으로 돌고 결과가 표시되는" 최소 단계다. 이를 브랜치 보호 규칙의 필수 상태 검사와 연결하면 테스트를 통과 못한 PR은 병합 버튼 자체가 비활성화된다.
¶ TodoBox로 보는 배포 자동화 흐름
TodoBox는 feature/*→dev→main의 3단 브랜치 구조를 쓰며, 이는 GitHub Flow에 "배포 전 통합 확인 지점"으로 dev를 하나 더 얹은 변형이다.
흐름은 다음과 같이 이어진다.
- feature 브랜치에서 PR을 올리면 GitHub Actions가 린트·테스트를 자동 검증한다.
dev로 머지되면 Vercel의 GitHub 통합을 통해 프리뷰 배포가 자동 생성된다.main으로 머지되면 프로덕션 배포가 실행된다.
이 절의 목적은 세부 YAML 문법이 아니라 "PR 하나가 어떻게 실제 배포로 이어지는가"라는 전체 흐름을 이해시키는 데 있으며, Vercel 세부 설정은 4권, 파이프라인 고도화는 7권에서 이어진다.
¶ 오픈소스 협업 관례에서 참고할 점
사내 전용 저장소라도 오픈소스 관례는 그대로 참고할 가치가 있다. "누가 무엇을 처리해야 하는지"를 사람의 기억이 아니라 저장소 구조가 안내하게 만들기 때문이다.
CONTRIBUTING.md로 기여 절차를 문서화한다.- 이슈 템플릿으로 버그/기능요청 형식을 통일한다.
CODEOWNERS와 라벨 체계를 결합한다.
¶ 핵심 포인트
이 책은 다음 세 가지가 서로를 지탱하는 구조로 정리된다.
- 컨벤션(브랜치·커밋·PR 규칙)
- 코드리뷰 문화
- CI/CD 구성
컨벤션 없이는 리뷰 기준이 없고, 리뷰 없이는 컨벤션이 문서로만 남으며, CI/CD 없이는 리뷰를 통과한 코드조차 실제 동작을 보장할 수 없다.
¶ 참고할 만한 사례
- 우아한형제들(배달의민족) 안드로이드팀은 팀 규모·작업 병렬성이 커지자 GitHub Flow에서 Gitflow로 전략을 전환했다.
- 화해(Hwahae) 역시 정기배포 주기에 맞춰 브랜치 전략을 재설계했다.
- GitHub Flow 자체는 GitHub 공동창업자 Scott Chacon이 2011년 자사 내부 배포 방식을 블로그에 정리하며 알려졌다.
- Google은 10억 줄 규모의 단일 저장소(monorepo)와 Trunk-based Development를 결합해 3만 5천 명 규모 조직을 운영한다.
¶ 💬 질문이 있으신가요?
아래 댓글로 남겨주세요. 로그인 없이도 바로 남길 수 있습니다.