왜 체크아웃이 병목이 되는가
모노레포가 커지면 CI 파이프라인의 첫 단계인 git checkout부터 무거워진다. 저장소 전체가 수 GB에 달하면, 실제로는 특정 서비스 디렉터리 하나만 빌드하는 잡(job)조차 전체 워킹 트리를 디스크에 펼쳐야 한다. 네트워크 전송, 디스크 I/O, 파일 생성 syscall이 모두 파일 수에 비례해 늘어난다. 러너가 stateless 컨테이너라면 캐시도 없어 매 실행마다 이 비용을 반복한다.
문제의 핵심은 두 가지다. 첫째, 히스토리를 얼마나 가져올지(fetch depth). 둘째, 워킹 트리에 얼마나 많은 파일을 펼칠지(checkout scope). 전자는 --depth로, 후자는 sparse checkout으로 제어한다.
shallow clone만으로는 부족한 이유
--depth=1은 커밋 히스토리를 줄여 전송량을 낮추지만, 워킹 트리에 펼쳐지는 파일 개수는 그대로다. 100만 파일 모노레포에서 서비스 하나만 필요해도 전부 디스크에 쓰인다. sparse checkout은 이 워킹 트리 범위 자체를 좁혀, 실제 필요한 경로만 파일로 물질화(materialize)한다. 두 기법은 상호 보완적이며 함께 쓰는 것이 정석이다.
cone 모드 sparse checkout 기본
Git 2.25+의 cone 모드는 디렉터리 단위로 범위를 지정해 매칭 성능이 좋다. blobless clone(--filter=blob:none)과 결합하면 파일 내용조차 필요할 때만 지연 다운로드된다.
#!/usr/bin/env bash
set -euo pipefail
# 트리와 커밋만 받고 blob은 지연 로딩
git clone --filter=blob:none --no-checkout --depth=1 \
https://example.com/org/monorepo.git repo
cd repo
# cone 모드 활성화 후 필요한 디렉터리만 지정
git sparse-checkout init --cone
git sparse-checkout set services/payments libs/common
git checkout main
set에 나열한 디렉터리와 저장소 루트의 파일만 워킹 트리에 나타난다. 이후 git sparse-checkout add로 범위를 넓힐 수 있다.
GitHub Actions 적용 예시
actions/checkout는 v4부터 sparse-checkout 입력을 지원한다. 별도 스크립트 없이 선언적으로 범위를 좁힐 수 있다.
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
sparse-checkout: |
services/payments
libs/common
sparse-checkout-cone-mode: true
- name: Build
working-directory: services/payments
run: make build
루트 파일(예: Makefile, go.work)은 cone 모드에서 자동 포함되므로 공용 설정 파일 접근도 문제없다.
기법별 비교
| 기법 | 줄이는 대상 | 주 사용처 |
|---|---|---|
| --depth=1 | 커밋 히스토리 전송량 | 빌드/테스트 잡 대부분 |
| --filter=blob:none | blob 다운로드(지연 로딩) | 일부 파일만 읽는 잡 |
| sparse-checkout | 워킹 트리 파일 수 | 모노레포 부분 빌드 |
주의점
몇 가지 함정이 있다. 빌드 도구가 sparse-checkout set에 없는 경로를 참조하면 파일이 없어 실패한다. 의존 그래프를 먼저 파악해 필요한 디렉터리를 빠짐없이 나열해야 한다. 커버리지 리포트나 lint가 저장소 전체를 훑는 경우에도 범위 밖 파일이 누락된다.
git blame이나 태그 기반 버전 계산처럼 히스토리가 필요한 스텝이 있으면 fetch-depth: 0과 충돌한다. 이런 잡은 sparse 범위와 depth를 별도로 조정하라. 또한 non-cone 모드는 .gitignore 스타일 패턴을 쓰지만 대규모에서 느리므로, 특별한 이유가 없으면 cone 모드를 권장한다.
효과 측정과 정착
적용 후에는 반드시 실제 수치를 비교하라. 체크아웃 스텝의 소요 시간과 워킹 트리 파일 수(git ls-files | wc -l)를 before/after로 기록하면 개선 폭이 명확해진다. 파일 수가 수십만에서 수천으로 줄면 checkout 단계가 수 분에서 수 초 수준으로 떨어지는 경우가 흔하다. 범위는 서비스 구조가 바뀔 때마다 갱신해야 하므로, sparse 경로 목록을 각 서비스의 CI 설정 가까이에 두고 코드 리뷰 대상으로 관리하는 것이 유지보수에 유리하다.