Copybara로 이해하는 저장소 간 코드 동기화와 변환 자동화

이 글은 여러 Git 저장소에 동일하거나 유사한 소스 코드를 유지해야 하는 상황에서 Copybara가 어떤 문제를 해결해 주는 도구인지, 왜 필요한지, 그리고 실제로 어떻게 사용하는지를 정리한 기술 블로그입니다. 저장소 간 코드 이동과 변환을 반복적으로 수행해야 하는 개발 환경에서 Copybara의 개념, 배경, 핵심 특징, 활용 방식까지 한 번에 이해할 수 있도록 구성했습니다.

반응형

---

Copybara란 무엇인가

Copybara는 서로 다른 저장소 간에 코드를 이동하고(transform) 동기화하는 도구입니다. 내부적으로는 Google에서 사용되던 도구로, 하나의 코드베이스를 여러 저장소에서 관리해야 하는 상황을 전제로 설계되었습니다.

대표적인 예는 다음과 같습니다.

• 사내 전용(비공개) 저장소와 외부 공개 저장소를 동시에 운영하는 경우
• 특정 저장소의 일부 코드만 다른 저장소로 가져와야 하는 경우
• 기여는 여러 저장소에서 받되, 최종 기준 저장소는 하나로 유지해야 하는 경우

Copybara는 이런 상황에서 코드를 단순히 복사하는 수준을 넘어, 경로 변경, 코드 치환, 파일 이동 등 다양한 변환을 자동으로 적용하며 저장소 간 동기화를 수행합니다.

---

Copybara가 필요한 배경

실무에서는 소스 코드가 한 저장소에만 존재하지 않는 경우가 많습니다. 공개용 GitHub 저장소와 내부 저장소를 동시에 유지하거나, 레거시 저장소에서 신규 저장소로 코드를 이전해야 하는 상황도 흔합니다.

이때 수작업으로 코드를 옮기면 다음과 같은 문제가 발생합니다.

• 변경 사항 누락
• 경로, 네이밍 규칙 불일치
• 반복 작업으로 인한 실수
• 변경 이력 추적의 어려움

Copybara는 이러한 문제를 해결하기 위해 하나의 기준 저장소(authoritative repository) 를 정하고, 나머지 저장소와의 코드 이동을 규칙 기반으로 자동화합니다.

---

Copybara의 핵심 개념: 단일 진실의 원천

Copybara를 사용할 때 가장 중요한 개념은 authoritative repository입니다.

• 하나의 저장소를 “진실의 원천(source of truth)”으로 지정
• 다른 저장소들은 이 기준 저장소를 기준으로 동기화
• 다만, 변경은 어떤 저장소에서든 가능

예를 들어 공개 저장소에서 외부 기여자가 변경을 만들더라도, Copybara를 통해 해당 변경을 기준 저장소로 가져와 동일한 방식으로 병합할 수 있습니다. 이 과정에서 충돌이 발생하면 일반적인 Git 충돌 처리 방식과 동일하게 해결합니다.

---

상태를 저장하지 않는(stateless) 구조의 장점

Copybara의 중요한 특징 중 하나는 상태를 내부에 저장하지 않는 구조입니다.
도구 자체가 별도의 DB나 메타데이터를 유지하지 않고, 대상 저장소의 커밋 메시지 라벨에 상태를 기록합니다.

이 방식의 장점은 명확합니다.

• 여러 사람이 동일한 설정 파일로 Copybara를 실행해도 결과가 동일
• CI/CD나 서비스 계정에서 실행해도 일관성 유지
• 별도의 상태 관리 인프라가 필요 없음

즉, Copybara는 설정 파일과 저장소 상태만으로 동작하는 예측 가능한 도구입니다.

---

지원 저장소와 확장성

현재 Copybara가 공식적으로 지원하는 저장소 타입은 Git입니다.
Mercurial 저장소도 읽기는 가능하지만, 아직 실험적인 기능에 해당합니다.

다만 아키텍처 자체는 확장 가능하게 설계되어 있어, 필요에 따라 다른 유형의 저장소나 맞춤형 origin/destination을 추가할 수 있습니다. 향후 다른 저장소 타입에 대한 공식 지원도 예정되어 있습니다.

---

Copybara 설정 파일 구조 이해하기

Copybara는 .sky 확장자의 설정 파일을 사용합니다. 이 파일에는 다음 정보가 정의됩니다.

• 어떤 저장소에서(origin)
• 어떤 브랜치나 커밋을 기준으로
• 어떤 저장소로(destination)
• 어떤 변환 규칙을 적용해 이동할지

예시 설정의 핵심 흐름은 다음과 같습니다.

• GitHub 저장소의 master 브랜치를 origin으로 지정
• 로컬 Git 저장소를 destination으로 지정
• 특정 경로의 파일만 복사
• BUILD 파일 내 경로 문자열 치환
• 전체 코드를 특정 디렉터리로 이동

이처럼 Copybara는 단순 복사 도구가 아니라 코드 구조를 재작성하는 도구에 가깝습니다.

---

Copybara 실행 방식

기본적인 실행 흐름은 매우 단순합니다.

1. 대상 저장소를 준비하고 Git 저장소로 초기화
2. Copybara 설정 파일 작성
3. Copybara 명령어 실행

한 번만 실행해 코드 이전(Migration)을 할 수도 있고, 반복 실행을 통해 주기적인 동기화도 가능합니다. 특히 정기적인 코드 이동이 필요한 경우 Copybara의 강점이 더욱 분명해집니다.

---

설치 및 사용 환경 개요

Copybara는 여러 방식으로 사용할 수 있습니다.

• 미리 빌드된 바이너리 사용
• 소스 코드 직접 빌드
• Bazel 프로젝트에 외부 의존성으로 포함
• Docker 기반 실행

공통적으로 필요한 전제 조건은 Java 실행 환경이며, 최신 릴리스 기준으로는 Java Runtime 21 이상이 요구됩니다. Bazel 기반 프로젝트와의 궁합이 특히 좋다는 점도 특징입니다.

---

728x90

Copybara는 다음과 같은 상황에 특히 적합한 도구입니다.

• 여러 Git 저장소를 동시에 운영해야 하는 조직
• 공개/비공개 저장소 간 코드 동기화가 필요한 경우
• 코드 이동 시 구조 변경이나 변환이 필요한 경우
• 반복적인 코드 이전 작업을 자동화하고 싶은 경우

단일 기준 저장소를 중심으로 코드 이동을 체계화함으로써, 저장소 관리 복잡도를 크게 줄일 수 있습니다.
장기적으로는 코드 일관성 유지, 작업 효율 향상, 실수 감소라는 효과를 기대할 수 있으며, 저장소 전략을 보다 명확하게 설계하는 데에도 도움을 줍니다.

여러 저장소를 운영하며 “코드 이동이 항상 골칫거리”였다면, Copybara는 충분히 검토해 볼 만한 선택지입니다.

300x250

https://github.com/google/copybara?fbclid=IwY2xjawSx-a5leHRuA2FlbQIxMQBzcnRjBmFwcF9pZBAyMjIwMzkxNzg4MjAwODkyAAEecwQK3qej2QxKwMALtLRFDmeLLXn41FMt_y16pps12JJ_nt3dUFPIU62kvZM_aem_r8NY_fMABM7sgxzUfupJOg

GitHub - google/copybara: Copybara: A tool for transforming and moving code between repositories.