ユースケースで理解するCopybaraの使い道

はじめに

複数の Git リポジトリをまたいでコードを管理するとき、「差分をどうやって同期するか」「OSS 公開前に社内専用情報をどう除去・置換するか」という課題が出てきます。
Google が開発する Copybara は、それらを自動化する強力なツールです。

本記事では ユースケース → 実装例 → 概念解説 の順で、Copybara の代表的な機能

• git.mirror

• git.origin

• core.replace

を説明していきます。

Copybaraのインストールや基本の使い方は、ここで割愛しますので、Copybaraの公式GitHubプロジェクトをご参照ください。
本記事ではCopybaraのRelease v20250721を使っております。

---

ユースケース別の使い方

1. 単純なフォークの追従（git.mirror）

OSS プロジェクトをフォークしている場合、「 fork 元に追従したい」「 手元にある fork 先に反映したい 」ことがよくあります。
この場合に便利なのが git.mirror です。
これだけで fork 先と fork 元の双方向同期 が可能になります。
ただし「置換」や「除外」はできないので、純粋なコピー専用と考えるのがコツです。

git.mirror(
    name = "mirror_upstream",
    origin = "https://github.com/upstream/project.git",
    destination = "[e-mail]:myfork/project.git",
)

パラメータ・構成要素の解説

• name

  • Copybara 内でこのミラー定義を識別するための名前。

  • 実行時には copybara mirror mirror_upstream のように呼び出せます。

  • 複数の mirror を設定する場合、この名前で区別します。

• origin

  • コピー元となる Git リポジトリの URL。

  • ここでは fork 元プロジェクト を指定しています。

  • 例: https://github.com/upstream/project.git が設定されている場合、GitHub fork 元プロジェクトのデフォルトブランチが同期対象。

• destination

  • コピー先となる Git リポジトリの URL。

  • 通常は 自分の fork 先 や 社内リポジトリ を指定します。

  • 例: [e-mail]:myfork/project.git が設定されている場合、SSH 認証でアクセスし、自分の fork 先に push できるようにする。

---

2. 社内リポジトリから OSS 公開用への変換（git.origin + core.replace）

社内用コードをそのまま OSS として公開すると、内部 URL や秘密情報が混じることがあります。
この場合は コピー元を git.origin、コピー先を git.destination に明示し、その間に core.replace を挟みます。
これにより、「社内のホスト名 → 公開用ホスト名」、「著作権表記 → OSS 向け表記」といった差し替えが自動で行われます。

core.workflow(
    name = "oss_publish",
    origin = git.origin(
        url = "ssh://[e-mail]/internal/project.git",
        ref = "main",
    ),
    destination = git.destination(
        url = "[e-mail]:opensource/project.git",
        push = "main",
    ),
    transformations = [
        core.replace(before = "internal.example.com", after = "public.example.org"),
        core.replace(before = "© 2025 CompanyX", after = "© 2025 OpenSource Community"),
    ],
)

パラメータ・構成要素の解説

• core.workflow

  • Copybara の中心となる「変換処理の定義ブロック」。

  • origin（コピー元）と destination（コピー先）、さらにその間で実行する transformations をまとめて指定します。

• git.origin

  • コピー元リポジトリを定義します。

  • url: Git リポジトリの場所（ここでは社内 Git サーバの SSH アクセス URL）。

  • ref: コピー対象のブランチやタグ。多くの場合 main や master を指定。

  • 例: ssh://[e-mail]/internal/project.git → 社内の「internal/project」リポジトリをソースにする。

• git.destination

  • コピー先リポジトリを定義します。

  • url: GitHub 上の公開リポジトリ URL。

  • push: 変換後に push するブランチ名。

  • 例: [e-mail]:opensource/project.git → 公開用 OSS リポジトリの main に push。

• transformations

  • コピー中に適用する「変換ルール」のリスト。

  • 複数の core.replace や core.move などを並べて順番に実行できます。

• core.replace

  • ファイル中の文字列を置換するシンプルな変換。

  • before: 検索対象の文字列や正規表現。

  • after: 置換後の文字列。

  • 複数指定すると上から順に適用される。

---

最後にまとめ

ユースケースごとに整理すると、Copybaraの使い方は次のようにまとめられます。

• フォークの単純追従 → git.mirror

• 社内コードを OSS 用に変換 → git.origin + core.replace

Copybara は「コピーの先と元の定義（git.origin/git.destination）」と「途中の変換（core.replace/transform）」を組み合わせる設計です。
このパターンを理解すれば、社内 ↔ OSS　などさまざまなシナリオに応用できます。

本文章が掲載したソースコードはサンプルであり、ソースコードを使用することで発生するいかなる損害や不利益について、当社は一切の責任を負いません