Google 开源内部代码迁移工具 Copybara

想象这样一个场景：你的团队在一个巨大的 monorepo 里做日常开发，内部工具、产品代码、基础设施配置全在里面。但与此同时，你需要将其中一部分代码开源——可能是某个 SDK、一个标准库，或者一个独立的功能模块。你当然可以手动复制粘贴，但几天后，内部仓库的代码又更新了，你还需要再同步一次。更糟的是，外部贡献者提交了 PR，这个修改也要回流到内部仓库。

这不是一个假设性问题。Google 在过去十几年里每天都要面对这个挑战——他们的内部 monorepo（Piper）拥有超过 20 亿行代码，而像 TensorFlow、Angular、Protobuf 这样的知名开源项目需要持续与 GitHub 上的公开仓库保持同步。

Copybara 就是 Google 为这个问题构建的内部工具。现在，它已经完整开源在 GitHub 上。

Copybara 是什么

Copybara 是一个用于在代码仓库之间进行转换和迁移的声明式工具。它的核心定位极其明确：在多个仓库之间移动代码，并在此过程中保持提交历史、作者信息和变更元数据的完整性。

从 README 的描述来看，Copybara 的设计哲学有三个关键点：

单一事实来源。 你需要在多个仓库中指定一个权威仓库（authoritative repository）。所有仓库都可以接受贡献，任何一个仓库都可以用作发布源，但始终存在一个”真相来源”来避免状态分叉。

无状态运行。 Copybara 本身不维护任何数据库或中间状态。它把状态信息以标签的形式直接存放在目标仓库的提交消息中。这意味着多个用户或 CI 服务可以同时使用相同的配置运行 Copybara，得到完全一致的结果。这种设计也意味着 Copybara 天然适合 CI/CD 管道集成——不需要部署任何持久化服务。

声明式配置。 Copybara 使用 Starlark（Bazel 的配置语言，一个 Python 方言）来描述迁移工作流。一份典型的 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",
    ),
    destination_files = glob(["third_party/copybara/**"], exclude = ["README_INTERNAL.txt"]),
    authoring = authoring.pass_thru("Default email <[email protected]>"),
    transformations = [
        core.replace(
            before = "//third_party/bazel/bashunit",
            after = "//another/path:bashunit",
            paths = glob(["**/BUILD"])),
        core.move("", "third_party/copybara")
    ],
)

从这份配置可以直接看出 Copybara 的完整工作流：从哪个仓库拉取代码、代码路径的映射规则、需要执行哪些文本替换和路径重定向，以及目标仓库的推送地址。整个过程不需要任何代码之外的中间步骤。

核心架构：迁移即转换管道

Copybara 将代码迁移建模为一个”转换管道”（transformation pipeline）。每一步转换都是管道中的一个独立操作，按顺序执行：

1. Origin（源）： 从源仓库读取代码和元数据。目前主要支持 Git，对 Mercurial 提供实验性支持。架构设计上保持可扩展性，理论上可以接入任何版本控制系统。

2. Transformations（转换）： 一系列声明式或可编程的代码变换，包括：

   • core.move：文件/目录的重定位
   • core.replace：文本内容的查找替换，支持正则和 glob 路径过滤
   • core.dynamic_transform：自定义 Python 函数，可执行任意复杂的变换逻辑
   • core.filter：基于文件路径或内容条件的过滤
   • authoring.pass_thru / authoring.overwrite：作者信息处理策略

3. Destination（目标）： 将变换后的代码写入目标仓库。

4. Metadata（元数据）： 在每个目标仓库的提交中嵌入 GitOrigin-RevId 标签，记录该提交在源仓库中的对应版本。这个标签是 Copybara 实现迭代同步和循环检测的关键。

这个管道模型的一个精妙之处在于：它把”代码迁移”这个看似复杂的操作解耦为一系列简单、可组合、可测试的步骤。每个步骤的输入和输出都是确定性的，这让调试和验证变得直接——你可以逐步骤查看中间结果，快速定位问题所在。

图源：Dagster 官方博客《Monorepos, the hub-and-spoke model, and Copybara》（2026-04-03）

双向同步：从理论到实践

Copybara 文档中提到，它支持”contributions to any repository”——任何仓库都可以接受贡献。但在原生的设计哲学中，它更倾向于单向同步：从一个权威仓库向其他仓库推送变更。

真正的挑战在于双向同步——当外部仓库也接受 PR 时，如何避免变更在两个仓库之间形成无限循环？

Dagster 团队在 2026 年 4 月发表的技术博客中详细描述了他们的解决方案。Dagster 的架构是一个典型的 hub-and-spoke 模型：内部 monorepo 是 hub，dagster-io/dagster 和 dagster-io/skills 等公开仓库是 spoke。

双向同步的核心机制是自定义 Revision ID。Copybara 默认会在每个提交中嵌入 GitOrigin-RevId 标签，标记该提交的源版本。Dagster 团队对此做了关键扩展：

• 内部→公开同步时，使用 Internal-RevId（而非默认的 GitOrigin-RevId）
• 公开→内部同步时，使用 Dagster-RevId
• 每个同步方向的 custom_rev_id 互不相同

然后，在转换管道中通过 dynamic_transform 添加跳过逻辑：

def _skip_synced_from_dagster(ctx):
    if ctx.find_label("Dagster-RevId"):
        core.fail_with_noop("Skipping commit that originated from dagster-io/dagster.")

当一个提交从内部仓库同步到公开仓库后，公开仓库中的对应提交带有 Internal-RevId 标签。当公开仓库的变更（包括这个提交）被同步回内部仓库时，跳过函数会检测到 Internal-RevId 标签，直接返回 no-op——这样就打破了循环。

这套机制的优雅之处在于：所有循环检测信息都存在 Git 提交历史中，Copybara 本身仍然是”无状态”的。不需要额外的数据库、锁服务或协调系统，只需要正确的配置和可靠的 CI 管道。

生产环境中的竞态处理

双向同步引入了一个微妙的竞态问题。Dagster 团队在实践中发现：如果内部仓库有一个变更正在等待 Copybara 同步到公开仓库，而此时公开仓库的一个 PR 先合入了 master，那么公开仓库的 Copybara 回同步操作可能会”覆盖”尚未同步的内部变更——导致静默回退。

他们的解决方案是引入一个 Sync Gate（同步门禁）。具体做法：

1. 在 GitHub 仓库配置 Merge Queue（合并队列）
2. 在合并队列触发时，运行一个 GitHub Actions workflow 检查同步状态
3. 检查逻辑：查询公开仓库 master 分支最近 100 个提交，找到最后一个带有 Internal-RevId 标签的提交，然后对比该提交与内部仓库 master 之间的差异
4. 如果发现内部仓库有未同步的变更且这些变更涉及公开仓库的代码路径，则阻塞合并
5. 轮询最多 10 分钟（每 20 秒检查一次），等待 Copybara 同步完成

这个设计的巧妙之处在于，它将”竞态问题的检测”完全表达为 Git 历史查询——不需要在 Copybara 内部引入分布式锁或其他协调原语。Copytara 的提交标签机制在这里体现了其设计的深远意义：可追溯性和安全检查点是同一个机制的两个侧面——标签既是历史记录，也是循环检测和同步门禁的基础设施。

竞品对比与生态定位

Copybara 并不是代码仓库同步领域的唯一方案。HN 讨论中提到了几个代表性的替代品：

Git Submodules / Subtrees。 最轻量的方案：无需额外工具，直接用 Git 内置功能。Submodules 将外部仓库作为”指针”嵌入，Subtree 则将外部仓库的历史合并到子目录中。但这两种方案都不支持代码变换——你无法在同步过程中自动替换 import 路径、重写构建配置、移除内部文件。它们只是”搬运”代码，而 Copybara 是”改造”代码。

Josh。 Rust 项目使用的工具，通过代理层将 monorepo 的子树呈现为独立的 Git 仓库。Josh 的设计更偏向”虚拟视图”——它不实际复制代码，而是动态映射。这使得它在大型仓库的场景下更高效，但灵活性不如 Copybara 的转换管道模型。

Jujutsu (jj)。 有 HN 用户指出，使用 jj 也能实现基本的”从私有 monorepo 维护公开仓库”的工作流，且代码量很少。但 jj 的方案更像是利用其强大的历史重写能力进行手动操作，而 Copybara 是专门为此场景设计的自动化工具。

Copybara 的真正护城河在于三点：代码变换能力（同步过程中自动执行路径重写、内容替换、文件过滤），提交元数据的系统性保留（不仅仅是 author，还包括完整的追溯链），以及无状态的 CI 集成设计（不需要持久化服务，纯配置文件驱动）。

谁在使用 Copybara

Google 内部自不必说——Copybara 是连接 Piper 和 GitHub 的基础设施组件，有专门的团队维护。TensorFlow、Angular、Protobuf 等 Google 的知名开源项目都依赖 Copybara 进行内外代码同步。

开源社区方面，Dagster 是公开分享过 Copybara 使用经验的最典型用户。他们的场景与 Google 高度类似：一个内部 monorepo 包含产品代码和内部工具，多个公开仓库作为外部接口，需要双向同步。

HN 评论中也透露出 Copybara 在更广泛场景中的应用。一位用户提到，他们在五年前用嵌套 Git 仓库和脚本实现过类似功能，现在看到 Copybara 开源感到非常认同——“Naming is hard and important.” 另一位曾在 Google 工作的用户表示：“我在 Google 时用过这个工具，对于将代码从 Google3 开源到 GitHub 极其有帮助。不过，我还是更开心现在能直接在 GitHub 上开发。”

还有用户指出一个有趣的安全视角：Copybara 这种强大的代码自动同步能力，如果被滥用，也可能被用于在 GitHub 上实施恶意软件投毒——将恶意代码从”干净”的公开仓库面纱后注入。

技术栈与使用方式

Copybara 本身使用 Java 编写，用 Bazel 构建。发行方式包括：

• 预编译 JAR： 从 GitHub Releases 下载 copybara_deploy.jar，需要 JDK 21+
• Bazel 外部依赖： 可以在自己的 Bazel 项目中以 http_jar 方式引入 Copybara
• Docker： 提供 Dockerfile，支持容器化运行
• Arch Linux AUR： 社区提供了 copybara-git 包

运行方式极其简单：

copybara copy.bara.sky

一个命令、一个配置文件，没有守护进程，没有数据库依赖。这种极简的操作模型让它非常适合嵌入 CI 管道——无论是 GitHub Actions、Buildkite 还是 Jenkins，都只需要安装 Copybara 二进制文件并执行对应命令。

局限与取舍

Copybara 并非银弹。从 Dagster 团队的经验中可以看到几个明显的局限性：

原生不支持真正的双向同步。 它的”blessed path”始终是单向同步+单一事实来源。Dagster 团队为了实现严格的双向同步不得不引入自定义 Revision ID、自定义跳过逻辑和 Sync Gate——这些都不是 Copybara 的内置功能。

Git 中心化。 虽然架构上声称可扩展，但目前对非 Git 仓库的支持仅限于 Mercurial（且仍标记为实验性）。如果你使用的是 Perforce、SVN 或其他 VCS，可能需要自行实现 Origin/Destination 接口。

配置复杂度随场景增长。 对于简单的单向导出，配置非常精简。但一旦引入双向同步、多仓库、代码变换的组合，copy.bara.sky 文件就会显著膨胀，需要团队投入精力维护。

Java 技术栈。 对于不使用 Bazel 和 Java 生态的团队来说，Copybara 的构建和运行环境是一个额外的依赖负担。Docker 方式缓解了这个问题，但仍然增加了 CI 管道的复杂性。

总结

Copybara 的核心理念超越了”代码复制”这个朴素概念。它将仓库间迁移定义为一个可编程的转换管道，把代码同步从手工操作升格为基础设施即代码的实践。无状态设计让它可以无缝嵌入任何 CI 环境；提交标签机制不仅提供了可追溯性，还在双向同步场景中充当了循环检测的基石。

对于已经或正在考虑采用 monorepo 策略的团队，Copybara 提供了一个经过 Google 内部十多年检验的实践参考——即便不直接使用这个工具，其架构设计中的”转换管道”、“无状态同步”、“标签驱动循环检测”等模式也值得借鉴。当你的团队从”现在只有一个仓库”走向”需要一个仓库体系”时，这些设计决策会体现出它们的价值。

本文的素材来自公开信息和社区讨论。如果你对这个话题有更深入的一手经验，欢迎指出文中的不足。

参考链接

• Copybara GitHub 仓库
• Dagster: Monorepos, the hub-and-spoke model, and Copybara
• Kubesimplify: Moving code between Git repositories with Copybara
• HN 讨论：Google Copybara 开源
• Josh Project：Rust 使用的 monorepo 同步工具
• JJ Public-Private Workflow
• Google: Why Google Stores Billions of Lines of Code in a Single Repository (2016)