---
title: "구글 Copybara, 비공개 저장소와 공개 저장소 사이에서 코드 옮기는 도구"
published: 2026-06-30T23:45:39.000Z
canonical: https://jeff.news/article/4499
---
# 구글 Copybara, 비공개 저장소와 공개 저장소 사이에서 코드 옮기는 도구

구글의 Copybara는 여러 저장소 사이에서 코드를 변환하고 이동시키는 도구다. 비공개 저장소와 공개 저장소를 동기화하거나, 외부 기여를 권위 저장소(authoritative repository)로 가져오는 반복 작업에 초점이 맞춰져 있다.

- 구글 Copybara는 저장소 사이에서 코드를 “그냥 복사”하는 도구가 아니라, 변환 규칙까지 적용해서 반복적으로 옮기는 도구임
  - 대표 케이스는 회사 내부 비공개 저장소와 GitHub 같은 공개 저장소를 계속 맞춰두는 상황
  - 공개 저장소에 들어온 기여를 내부 원본 저장소의 적절한 위치로 옮기는 흐름도 지원함

- 핵심 설계는 “권위 저장소(authoritative repository)”를 하나 정하는 것
  - 여러 저장소가 있어도 진짜 source of truth는 하나여야 충돌과 릴리스 기준이 덜 꼬임
  - 그렇다고 기여를 한 저장소에서만 받아야 하는 건 아님. 어느 저장소에서든 변경이 들어올 수 있고, Copybara가 변환해서 권위 저장소로 밀어 넣는 구조임
  - 릴리스도 특정 저장소에만 묶이지 않고, 어떤 저장소에서도 끊을 수 있게 설계돼 있음

- Copybara가 흥미로운 지점은 상태 관리 방식임
  - 별도 DB나 중앙 서비스에 상태를 들고 있는 게 아니라, 대상 저장소의 커밋 메시지 라벨에 상태를 저장함
  - 그래서 여러 개발자나 자동화 서비스가 같은 설정과 같은 저장소 조합으로 실행해도 같은 결과를 기대할 수 있음
  - 저장소 동기화 도구에서 “누가 언제 돌렸는지” 때문에 결과가 달라지는 문제를 줄이려는 선택임

- 현재 기본 지원 저장소는 Git임
  - Mercurial 저장소에서 읽는 기능은 있지만 아직 실험적이라고 못 박아둠
  - 구조 자체는 확장 가능하게 만들어져 있어서, 필요하면 커스텀 origin이나 destination을 붙이는 식으로 다른 저장소나 내부 시스템에도 맞출 수 있음

- 설정은 `copy.bara.sky` 같은 파일에 워크플로로 선언하는 방식임
  - 예시에서는 GitHub 원본에서 코드를 읽고, 로컬 Git 저장소로 내보내는 destination을 지정함
  - `destination_files`로 옮길 파일 범위를 고르고, `core.replace`로 BUILD 파일 안의 경로를 바꾸고, `core.move`로 전체 경로를 `third_party/copybara` 아래로 이동시킴
  - 설정 파일도 VCS에 넣어서 소스 코드처럼 관리하라고 권장함. 이건 꽤 현실적인 조언임

> [!IMPORTANT]
> Copybara의 포인트는 “한 번 옮기기”보다 “계속 옮기기”임. 내부/외부 저장소를 장기간 같이 굴릴 때 반복 작업과 규칙 누락을 줄이는 쪽에 가깝다.

- 설치와 실행은 선택지가 꽤 많음
  - 가장 쉬운 시작점은 주간 스냅샷 릴리스 바이너리지만, 자동으로 만들어지는 릴리스라 수동 테스트나 호환성 보장은 없음
  - HEAD에서 직접 빌드하려면 JDK 11과 Bazel이 필요하고, `bazel build //java/com/google/copybara`나 deploy jar 타깃을 빌드하는 흐름을 쓴다
  - 주간 스냅샷 jar는 class file version 65.0이라 Java Runtime 21 이상으로 실행해야 함

- Bazel 워크스페이스에 도구로 박아 넣는 흐름도 제공함
  - `http_jar`로 릴리스 jar를 받아오고, BUILD 파일에서 `java_binary`를 선언한 뒤 `bazel run //tools:copybara -- migrate copy.bara.sky`처럼 실행하는 방식
  - Copybara 의존성을 워크스페이스에 직접 가져와 `bazel run @com_github_google_copybara//java/com/google/copybara -- <args...>` 형태로 돌리는 방법도 있음

- Docker 사용도 가능하지만 아직 실험적임
  - `docker build --rm -t copybara .`로 이미지를 만들고, 작업 디렉터리를 `/usr/src/app`에 마운트해서 실행하는 식
  - `COPYBARA_SUBCOMMAND`, `COPYBARA_CONFIG`, `COPYBARA_WORKFLOW`, `COPYBARA_SOURCEREF`, `COPYBARA_OPTIONS` 같은 환경변수로 실행 동작을 바꿀 수 있음
  - Git 설정이나 SSH 키를 컨테이너에 넘기는 예시도 있지만, 이 부분은 팀 보안 정책을 먼저 봐야 할 포인트임

---

## 기술 맥락

- Copybara가 해결하려는 문제는 “저장소가 여러 개인데 코드는 사실상 하나”인 상황이에요. 회사 내부 구현은 비공개로 두고, 일부만 공개 저장소에 내보내야 할 때 사람이 매번 파일을 골라 옮기면 실수하기 쉽거든요.

- 그래서 이 도구는 어느 저장소가 기준인지 먼저 정해요. 권위 저장소를 정하지 않으면 공개 저장소의 변경과 내부 저장소의 변경이 서로 충돌할 때 무엇을 맞다고 볼지 애매해지기 때문이에요.

- 변환 규칙을 설정 파일로 관리하는 것도 중요한 선택이에요. 경로 이동, 파일 제외, 문자열 치환 같은 작업을 코드 리뷰 가능한 형태로 남겨야 나중에 “왜 이 파일은 빠졌지?” 같은 문제가 덜 생기거든요.

- 상태를 대상 저장소의 커밋 메시지 라벨에 넣는 방식은 중앙 서버 없이 반복 실행을 가능하게 하려는 설계예요. 여러 사람이 같은 마이그레이션을 돌려도 기준점이 저장소 안에 남아 있으니, 자동화 파이프라인에 붙이기도 비교적 편해요.

## 핵심 포인트

- 하나의 저장소를 진짜 원본(source of truth)으로 정하고, 나머지 저장소와 코드를 주고받는 모델임
- 상태를 별도 서버가 아니라 대상 저장소의 커밋 메시지 라벨에 저장해서 여러 사용자가 같은 설정으로 같은 결과를 얻을 수 있음
- Git 저장소를 기본 지원하고, Mercurial 읽기는 아직 실험적임
- Bazel 설정으로 워크플로, 파일 선택, 문자열 치환, 경로 이동 같은 변환을 선언할 수 있음
- 주간 스냅샷 바이너리는 자동 릴리스라 호환성이나 정확성 보장은 약함

## 인사이트

오픈소스 프로젝트를 회사 내부 저장소와 같이 운영해본 팀이면 이 문제 꽤 익숙할 거다. Copybara의 핵심은 단순 복사가 아니라, 저장소 간 경계와 변환 규칙을 코드처럼 관리하게 해준다는 점임.