Cross-Repository File Sync

크로스 레포지토리 파일 동기화입니다.

여러 개의 git 저장소 사이에서 공통 파일(설정, 스크립트, 문서 등)을 일관되게 유지하기 위한 기술과 전략의 총칭입니다.

발생 배경

모노레포(Monorepo) 대신 멀티레포(Multi-repo) 구조를 선택했을 때, 아래와 같은 파일들이 각 레포에 중복됩니다.

CI/CD 워크플로우 파일 (.github/workflows/*.yml)
공통 설정 파일 (.eslintrc, .prettierrc, Dockerfile)
라이선스, 기여 가이드 (LICENSE, CONTRIBUTING.md)
공유 스크립트, 유틸리티 함수

하나의 레포에서 수정하면 나머지 레포에도 전파해야 하는 동기화 문제가 발생합니다.

주요 접근 방식

1. Git Submodule

공유 파일을 별도 레포로 분리하고, 다른 레포에서 서브모듈로 포함하는 방식.

git submodule add https://github.com/org/shared-configs .shared

장점	단점
버전 고정 가능	업데이트 명령이 번거로움
git 기본 기능	클론 시 별도 초기화 필요
의존성 명시적	팀원 학습 비용

2. Git Subtree

서브모듈과 달리 외부 레포의 내용을 현재 레포에 직접 병합하는 방식.

git subtree add --prefix=shared/ https://github.com/org/shared-configs main --squash
git subtree pull --prefix=shared/ https://github.com/org/shared-configs main --squash

장점	단점
일반 파일처럼 다룰 수 있음	히스토리가 복잡해짐
별도 초기화 불필요	푸시 방향 관리 어려움

3. CI/CD 기반 자동 동기화

GitHub Actions 등을 이용해 소스 레포의 변경을 감지하고, 대상 레포에 자동으로 PR 또는 커밋을 생성하는 방식.

# .github/workflows/sync.yml (소스 레포)
on:
  push:
    paths:
      - 'shared/**'
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync to target repos
        uses: repo-sync/github-sync@v2
        with:
          source_repo: org/source-repo
          source_files: shared/
          destination_repo: org/target-repo
          destination_branch: main

대표 도구:

repo-sync/github-sync — GitHub 레포 간 파일 동기화 액션
BetaHuhn/repo-file-sync-action — 다수의 레포에 동시 동기화 지원
Copybara (Google) — 대규모 멀티레포 동기화

장점	단점
완전 자동화	CI 설정 복잡도 증가
유연한 필터링 가능	충돌 발생 시 수동 개입 필요

4. 패키지/모듈로 추상화

공유 파일을 npm, pip, Maven 등의 패키지로 배포하고, 각 레포에서 의존성으로 설치하는 방식.

// package.json
{
  "devDependencies": {
    "@org/shared-configs": "^1.2.0"
  }
}

ESLint, Prettier 설정 공유에 주로 사용
버전 관리가 명확하고 업데이트가 용이
파일 직접 편집이 어렵고, 배포 파이프라인 필요

전략 선택 기준

상황	권장 전략
레포 수 적고 수동 관리 가능	Git Subtree
공유 설정의 버전 고정이 중요	Git Submodule
레포 수 많고 완전 자동화 필요	CI/CD 기반 동기화
설정 파일을 표준화하고 배포	패키지 추상화

충돌(Conflict) 처리

동기화 중 대상 레포에서 해당 파일을 독립적으로 수정했을 경우:

Overwrite 방식 — 소스 레포를 항상 우선 (간단하지만 로컬 수정 손실 위험)
PR 방식 — 자동으로 PR 생성 후 수동 검토 (안전하지만 관리 비용 발생)
파일 잠금 — 대상 레포에서 해당 파일 수정을 lint/hook으로 차단

cross-repo-file-sync