요즘 팀 프로젝트 하다 보면 이런 고민, 진짜 많이 들어요.
“서비스도 늘고, 앱도 여러 개 생기는데… 저장소를 하나로 계속 끌고 가도 괜찮을까?”
처음엔 하나의 GitHub 저장소에서 다 같이 작업하니까 편했는데,
파일이 많아지고 CI/CD 설정도 꼬이다 보니 슬슬 ‘모노레포 vs 멀티레포’ 고민이 시작되더라고요.
저도 그랬습니다. 혼자 개발할 땐 신경 안 쓰다가, 팀 3~5명쯤 되니까 바로 문제가 튀어나오더라고요.
브랜치 충돌, 테스트 속도, PR 병합 순서… 하나하나가 다 협업 생산성과 직결되는 요소더라고요.
그래서 이 글에선, 저처럼 “어디까지 하나로 가져가야 하지?” 고민하는 분들을 위해
모노레포와 멀티레포의 차이, 장단점, 전환 타이밍, 실전 구조 예시까지 정리했습니다.
개발 경험이 많지 않아도 이해할 수 있게, 마트 비유부터 git 명령어 실습까지 차근차근 담았으니
당장 구조 고민 중이라면 이 글로 한번 정리해보세요!
📌 모노레포 vs 멀티레포개념 정의
- 모노레포(Monorepo):
여러 프로젝트(서비스)의 코드를 하나의 저장소에서 함께 관리하는 방식이에요. - 멀티레포(Multirepo):
프로젝트나 서비스마다 각자 다른 저장소를 사용하는 방식이에요.
🪄 모노레포 vs 멀티레포 비유 (쉽게 생각해봐요!)
- 모노레포는 대형 마트 하나에 모든 물건이 있는 것과 같아요.
한 군데만 가면 필요한 걸 다 살 수 있어요. 효율적이고 빠릅니다. - 멀티레포는 과일가게, 빵집, 정육점처럼 각각 따로 운영되는 시장이에요.
전문화는 잘 돼 있지만, 여러 군데를 돌아다녀야 해요.
💡 사용 예시 (실제 폴더 구조)
모노레포 구조 예시
project-root/
├─ core/ # 핵심 기능 모듈
│ ├─ module1/
│ ├─ module2/
│ └─ ...
├─ apps/ # 사용자-facing 앱들
│ ├─ app1/
│ ├─ app2/
│ └─ ...
├─ shared/ # 공통 코드
│ ├─ security/
│ └─ quality/
├─ infra/ # 배포, 도커 등 인프라 설정
├─ .github/
│ └─ workflows/ # GitHub Action 자동화 설정
└─ tasks.json # 작업 관리용 설정 파일
Git 브랜치 전략 예시
| 브랜치 | 설명 |
|---|---|
| main | 안정적인 버전, 실제 배포에 사용 |
| dev | 여러 기능을 통합해서 테스트하는 브랜치 |
| feat/ | 새로운 기능 작업용 개인 브랜치 → dev에 머지 (PR) |
🔄 멀티레포로 자연스럽게 전환하는 단계
- 특정 앱이 별도 팀에서 관리되면, 그 앱 폴더만 따로 새 저장소로 분리 bash복사편집
git filter-repo --subdirectory-filter apps/app1 --force - 공통 코드는
shared/디렉토리를 내부 패키지나 서브모듈로 분리해서 재사용 - 각 앱마다 자체적으로 CI/CD 자동화 구성 (서로 독립적으로 배포 가능하게)
🧠 어디서 쓰이나? (각 방식의 장단점)
✅ 모노레포가 유리한 경우
- 프로젝트 시작 단계
- 팀 규모가 작을 때 (2~5명)
- 기능들이 서로 자주 영향을 줄 때
- 테스트 및 수정 작업을 빠르게 하고 싶을 때
✅ 멀티레포가 유리한 경우
- 프로젝트가 커지고, 서비스끼리 완전히 독립적일 때
- 여러 팀이 나눠서 병렬적으로 개발할 때
- 서비스마다 배포나 보안 권한을 따로 관리해야 할 때
✅ 기억 꿀팁 한 줄 요약!
초기엔 한방에(모노), 커지면 나눠서(멀티)!
🚀 지금 당장 써먹는 실행 절차 (실습용 예시)
(1) GitHub 저장소 만들기 + 초기화
gh repo create my-monorepo --private
cd my-monorepo && git init
(2) 폴더 구조 스캐폴드 생성 & 첫 커밋
git add .
git commit -m "chore: initial scaffold with core & apps"
git push -u origin main
(3) GitHub Actions 자동 테스트 설정 (.github/workflows/ci.yml)
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pip install -r requirements.txt
- run: pytest
(4) VSCode 작업공간 설정
.code-workspace에core/,apps/폴더를 포함시켜서 검색과 테스트를 한 번에 하게 설정
(5) 릴리즈 태그 달기
git tag -a v0.1.0 -m "MVP scaffold"
git push origin v0.1.0
이제 모노레포로 시작해서 편하게 관리하고,
규모가 커질 땐 멀티레포로 자연스럽게 전환하면 됩니다! 😄
