Copybara 딥다이브
— 구글이 "레포 사이로 코드를 옮기고 변형"하는 도구

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 딱 한 줄이다: "A tool for transforming and moving code between repositories." ("저장소들 사이에서 코드를 변형하고 이동시키는 도구.") 이어서 "Copybara is a tool used internally at Google." — 즉 마케팅용으로 급조된 게 아니라 구글이 실제로 매일 쓰는 사내 도구를 오픈소스로 공개한 것이다.

가장 흔한 시나리오는 README의 표현대로 "maintaining a confidential repository and a public repository in sync" — 기밀 레포와 공개 레포를 계속 동기화하는 것이다. 규칙은 하나다: 둘 중 하나를 반드시 "권위 있는 원본(source of truth)"으로 정한다. 진실은 한 곳에만 있어야 충돌이 안 나기 때문이다. 다만 기여(contribution)는 어느 쪽에서 들어와도 되고, Copybara가 그걸 원본 쪽으로 다시 실어 나른다.

2왜 주목받는가

"구글이 진짜로 쓰는 도구" · Starlark 설정 · stateless 우아함 · git 표준 도구로는 안 되는 영역.

Copybara는 2016년부터 있던 오래된 프로젝트인데도 월간 트렌딩에 다시 올라왔다. 이유는 몇 가지가 겹친다. 첫째, "빅테크가 사내에서 실제로 굴리는 인프라 도구"라는 후광이다. Bazel(빌드), Copybara(레포 동기화)는 구글 오픈소스 릴리스 파이프라인의 두 축이라, "구글은 어떻게 모노레포를 GitHub에 뿌리나?"의 정답지 역할을 한다. 둘째, AI 코딩 시대에 여러 레포를 자동으로 오가며 코드를 옮기는 수요가 늘면서 다시 조명받았다.

git 기본 도구로는 왜 부족한가

주목도를 끌어올린 구체적 요인은 다음과 같다.

① 설정이 곧 코드 — Starlark. copy.bara.sky는 Bazel과 같은 Starlark 언어로 쓴다. Bazel을 쓰는 조직엔 이미 친숙한 문법이라 진입장벽이 낮고, 설정을 함수·변수·반복문으로 프로그래밍할 수 있다(정적 YAML보다 유연).
② 확장 가능한 플러그인 구조. Origin(어디서)·Destination(어디로)이 인터페이스로 추상화돼 있어 Git·GitHub·Gerrit·GitLab·로컬 폴더·Mercurial을 같은 방식으로 다룬다. 새 백엔드도 끼워 넣을 수 있다.
③ 가역 변환(reversible). "밖으로 내보낼 때 경로를 A→B로 바꿨다면, 안으로 받을 땐 자동으로 B→A로 되돌린다." 많은 변환이 역방향을 자동 계산하도록 설계돼, 양방향 동기화가 깔끔하다.
④ 코드가 곧 교과서. "설정 파일 언어를 프로그램에 임베딩하는 법"(Java에 Starlark 인터프리터를 심는 법)을 배우기에 이만한 실전 예제가 드물다. 뒤에서 자세히 본다.

3기술 스택 전체 지도

순수 Java(96%) + 임베딩된 Starlark 인터프리터 · Bazel(Bzlmod) 빌드 · JDK 21.

언어 구성은 단순하다 — Java 96.4%, Starlark 2.8%, 나머지가 셸·Docker·YAML이다. 여기서 "Starlark"는 두 얼굴을 가진다: (1) Bazel 빌드 파일(BUILD, .bzl)로서의 Starlark, 그리고 (2) 사용자가 쓰는 설정 파일(copy.bara.sky)을 실행하기 위해 Java 안에 심어 둔 Starlark 인터프리터. 제품 로직 자체는 100% Java다.

① 핵심 스택

② 코드 생성 · 로깅 · 파서

③ 테스트 스택 (구글 표준)

④ 배포 · 인프라

4아키텍처 심화 분석

Origin → Transformations → Destination 파이프라인 · 4가지 WorkflowMode · Starlark 임베딩.

Copybara의 심장은 core.workflow 하나다. 워크플로는 "어디서(origin) 읽어 → 무엇으로(transformations) 바꿔 → 어디로(destination) 쓸지"를 묶은 단위다. Java에서는 Workflow<O extends Revision, D extends Revision> 클래스가 이 모델을 담는다. 전체 흐름을 그림으로 보면 이렇다.

핵심: 4가지 WorkflowMode

같은 "이동"이라도 어떻게 커밋을 만드느냐가 상황마다 다르다. Copybara는 이를 WorkflowMode라는 Java enum 4종으로 못박아 뒀다.

설계 패턴 1 — Starlark를 Java에 임베딩하기

copy.bara.sky는 어떻게 실행될까? Copybara는 Bazel의 Starlark 인터프리터(net.starlark.java)를 그대로 내장한다. 파서는 config/SkylarkParser.java다. 흐름의 핵심 한 줄은 이렇다.

// config/SkylarkParser.java — 설정을 실행하는 핵심
Module module = Module.withPredeclared(semantics, environment);
// environment = core, git, folder, metadata... (자바로 만든 모듈들)
Program prog = Program.compileFile(StarlarkFile.parse(input, options), module);
// 이제 copy.bara.sky 안에서 core.workflow(...), git.origin(...) 호출 가능

즉 Java로 만든 모듈들을 "미리 선언된 전역(predeclared globals)"으로 주입해 두면, 설정 파일에서 core.workflow(...)처럼 바로 부를 수 있다. 어떤 Java 메서드를 설정에 노출할지는 어노테이션으로 표시한다.

// folder/FolderModule.java — 자바 메서드를 Starlark 함수로 노출
@StarlarkMethod(
    name = "origin",
    doc = "A folder origin is a origin that uses a folder as input...",
    parameters = { /* @Param(name="inside_symlinks_mode", ...) 등 */ })
public FolderOrigin origin(...) throws EvalException { ... }

이 모든 모듈이 한 곳 ModuleSupplier.java에서 인스턴스화·등록된다. CoreModule, GitModule, FolderModule, MetadataModule, Authoring.Module, HgModule, FormatModule, PatchModule, HttpModule … 여기가 "설정에서 쓸 수 있는 API 전체 목록"이다.

설계 패턴 2 — 가역 변환 (Reversible Transformations)

core.move("a", "b")는 순방향으로 a→b 경로 이동이다. Copybara는 이 변환의 역(reverse)을 자동으로 안다 — b→a. 그래서 core.reverse([...])로 워크플로 방향을 통째로 뒤집을 수 있고, 양방향 동기화가 성립한다. 되돌릴 수 없는 변환(예: 무조건 삭제)은 core.transform(..., reversal=[...])로 역방향을 명시해 줘야 한다. 내부적으로 ExplicitReversal·Sequence가 이 로직을 담당한다.

설계 패턴 3 — Stateless, 상태는 목적지에

앞서 말한 트레이드마크다. Copybara는 실행 이력을 목적지 커밋 메시지의 라벨(예: GitOrigin-RevId: abc123…)에 남긴다. 다음 실행 때 목적지의 최신 커밋에서 이 라벨을 읽어 "원본 어디까지 왔는지"를 복원한다. 외부 상태 저장소가 필요 없으니, 여러 사람·CI가 같은 설정으로 아무 때나 돌려도 결정론적으로 같은 결과가 난다.

5디렉토리 구조 해부

"Java 소스 한 트리 + 거울처럼 대응되는 테스트 트리 + 벤더링된 Starlark".

세 덩어리로 나눠 읽으면 명료하다.

① 제품 코드 java/com/google/copybara/. 여기가 전부다. 루트에 오케스트레이션 클래스(Main·Workflow·WorkflowMode·CoreModule·각종 *Cmd)가 있고, 그 아래 기능별 패키지가 붙는다. 가장 큰 패키지는 git/(59파일)로, GitHub·Gerrit·GitLab까지 커버하는 실제 세계의 주력이다.

② 거울 테스트 javatests/. 메인 트리와 패키지 구조가 1:1로 대응된다(구글 표준). 어떤 클래스의 동작이 궁금하면 같은 경로의 테스트 파일을 열면 사용 예가 나온다 — 테스트가 곧 문서다.

③ 벤더링된 Starlark third_party/.../net/starlark/java/. 설정 언어 엔진을 저장소 안에 통째로 넣어 뒀다(eval/·syntax/·annot/ 등). 3장에서 본 "핵심 의존성 내재화"의 실물이다.

6학습 포인트 (기술별)

이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.

7하드웨어 / 시스템 요구사항

무거운 GPU·서버가 필요 없다 — JDK와 git만 있으면 노트북에서 충분.

8직접 해볼 수 있는 실습 과제

난이도별로 손을 움직여 보는 5가지.

입문 ★☆☆

# 이미지 빌드 후 help
docker build --rm -t copybara .
docker run -it -v "$(pwd)":/usr/src/app copybara help

# copy.bara.sky (요지)
core.workflow(
    name = "default",
    origin = git.github_origin(url="https://github.com/google/copybara.git", ref="master"),
    destination = git.destination(url="file:///tmp/foo"),
    authoring = authoring.pass_thru("Me <me@example.com>"),
    transformations = [ core.move("", "third_party/copybara") ],
)

(mkdir /tmp/foo ; cd /tmp/foo ; git init --bare)
copybara copy.bara.sky --force   # 첫 이동은 --force

중급 ★★☆

고급 ★★★

9관련 기술 심화 학습 로드맵

4주 코스 — Starlark/Bazel 기초부터 직접 모듈 추가까지.

10핵심 키워드 사전

이 프로젝트를 읽을 때 반복 등장하는 용어 정리.

11참고 링크

원본을 직접 확인하고 싶을 때.