google/copybara: moving code between repositories without a shared state server

The problem: one codebase, two repositories, one source of truth

Source code often has to exist in more than one repository. A project may keep a confidential repository and a public repository in sync, or accept contributions in a public repository and pull them back into an internal one. Copybara is built for that situation. The README states the tool requires you to choose one repository as the authoritative repository, so there is always one source of truth, while still allowing contributions to any repository and releases cut from any repository. The audience is teams that already run Git and are willing to describe the movement of code as a configuration file rather than performing it by hand. The README lists three example uses: importing sections of code from a confidential repository to a public repository, importing code from a public repository to a confidential repository, and importing a change from a non-authoritative repository into the authoritative one, with merge conflicts handled the same way as an out-of-date change inside the authoritative repository. The project is used internally at Google, and the public repository is the same codebase.

Stateless by design: state lives in the destination commit message

The README calls statelessness one of the main features. Copybara does not keep a database of what it has already copied. Instead it stores its state in the destination repository as a label in the commit message. That choice is what lets several users, or a service, run the same configuration against the same repositories and get the same result. There is no coordination file to lock, and no drift between what a server thinks it did and what the destination actually contains. The cost is that the destination history becomes part of the tool's working memory, so rewriting or squashing destination commits removes the information Copybara uses to decide what is new. The README describes the currently supported repository type as Git. Mercurial repositories can be read, but the feature is still experimental, and official support for other repository types is described as a future addition. The architecture is extensible, so bespoke origins and destinations can be added for cases the built-in ones do not cover.

Writing a copy.bara.sky workflow and running it

A Copybara run is driven by a configuration file, conventionally named copy.bara.sky, written in a Python-like syntax. The README gives this example, which defines a workflow named default, reads from the GitHub origin at the master ref, writes to a local bare repository, copies only files under third_party/copybara, rewrites a Bazel label in BUILD files, and moves everything under third_party/copybara.

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")
    ],
)

The README then shows how to prepare a destination and run the workflow. The first command creates a bare Git repository at /tmp/foo, which is the destination URL used above. The second command runs the default workflow from the configuration file.

$ (mkdir /tmp/foo ; cd /tmp/foo ; git init --bare)
$ copybara copy.bara.sky

Note that the README recommends storing configuration files in version control and treating them as source code, even though they can live in any local folder. The transformations list is where the real work happens: core.replace rewrites strings in matching paths, and core.move relocates a tree. Order matters, since the replace runs before the move in this example.

Installing Copybara from a weekly snapshot or from source

The README says the easiest way to start is with the weekly snapshot releases, which include a pre-built binary, and points to the releases page for the list. It also carries an explicit warning: those releases are produced automatically without manual testing, version compatibility or correctness guarantees. For an unreleased version you build from HEAD, and the README lists the steps. JDK 11 and Bazel are prerequisites, the source is cloned from GitHub, and the build produces the tool and an executable uberjar.

git clone https://github.com/google/copybara.git
bazel build //java/com/google/copybara
bazel build //java/com/google/copybara:copybara_deploy.jar
bazel test //...

The README notes that some tests need the underlying tool installed, naming Mercurial and Quilt, and that skipping those is fine when a change is unrelated to those modules because CI runs the full suite. There is also an Arch Linux package, aur/copybara-git, and a Dockerfile in the repository that builds the deploy jar and copies it to /opt/copybara/copybara_deploy.jar with an entrypoint at /usr/local/bin/copybara. If you consume the snapshot jar from Bazel instead of running it directly, the README's instructions differ on the runtime: it says the snapshot ships class files with version 65.0, so it must run with Java Runtime 21 or greater, and gives the .bazelrc line run --java_runtime_version=remotejdk_21. The source build instructions list JDK 11. That gap is worth checking before you pick a path.

Where Copybara is the wrong tool

The narrowest constraint is repository support. The README states the only supported type of repository is Git, and that Mercurial reading is experimental. If your destination is not Git, the built-in destinations will not serve you, and you would be relying on the extensible architecture to write your own. The weekly snapshot warning is the second limitation: the README says those releases are automatic and come without manual testing, version compatibility or correctness guarantees, so a team that needs a vetted binary has to build from source and run the test suite itself. The stateless model has a failure mode too. Because the state is a label in the destination commit message, anything that discards or rewrites destination history removes the record Copybara depends on, and the next run has no way to know what was already moved. The README does not document rollback. There is also no hosted service described here: Copybara is a binary and a configuration file that you run, in CI or by hand, and you own the scheduling, credentials and error handling around it.

How Copybara differs from a mirroring job

The obvious alternative is a plain mirror: push or pull between two remotes and keep them identical. That approach has no notion of the authoritative repository, no way to exclude a file such as README_INTERNAL.txt from the destination, and no place to express a rewrite like changing //third_party/bazel/bashunit to //another/path:bashunit on the way through. Copybara's workflow is a pipeline with an origin, a destination, a file filter and a list of transformations, so the two repositories can differ in layout and in identifiers while still being derived from each other. A mirror job also has to track what it already synced, usually outside the repositories, whereas Copybara reads that from the destination commit message. The trade-off runs the other way as well: a mirror is a Git command anyone on the team already understands, while Copybara asks you to learn a configuration language and to keep the file under version control. If the two repositories should be byte-identical, a mirror is simpler. If they should not, Copybara is the tool that expresses the difference.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-22. The release list shows a weekly cadence: v20260907, v20260914 and v20260921, each published a few days apart. That cadence is the maintenance model, and it is also the upgrade cost. Because the README describes the snapshots as automatic and without version compatibility guarantees, upgrading means moving to a new binary every week and accepting that no compatibility promise was made between them. Pinning a specific release and testing it against your configuration is the only way to make an upgrade predictable. The project is licensed under Apache-2.0, which permits commercial use and modification and requires that the licence and notices be preserved; the LICENSE file sits at the repository root. The README does not describe any commercial support offering, so the practical support channel is the repository itself. Configuration files are yours and are not covered by the project's licence, but if they embed credentials or internal URLs, treat them with the same care as any other source file.

Editorial conclusion

Adopt google/copybara when you maintain a confidential and a public repository and need repeatable, reviewable transforms between them. Skip it if your repositories are not Git and you need a supported Mercurial path, or if you want a hosted service rather than a binary you run yourself. Before committing, verify the Java runtime against the class file version you download: the README says the snapshot jar ships class files at version 65.0 and needs Java 21 or greater, while building from source lists JDK 11. Also confirm that the weekly snapshot warning is acceptable for your pipeline, since the README states those releases ship automatically without manual testing or correctness guarantees.

Frequently asked questions

Official sources

1. google/copybara on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases