跳到主要内容

功能简介

仓库镜像管理功能用于配置和管理仓库镜像；配置仓库镜像可以实现不同平台之间仓库分支、标签和提交信息的自动同步。

目前该功能限时开放至 2022 年 08 月 31 日，在限时开放期结束前，我们将更新相关产品策略。

Gitee 支持设置两种镜像：

  • Push：用于将 Gitee 的仓库自动镜像到 GitHub 。

    配置此镜像后，当你提交代码到 Gitee 的仓库时，Gitee 会自动向 GitHub 同步仓库。

    Push

  • Pull：用于将 GitHub 的仓库镜像到 Gitee 。

    你可以根据自身需求选择 自动镜像 或 手动镜像；

    自动镜像：当你提交代码到 GitHub 镜像仓库时，Gitee 会自动从 GitHub 同步仓库；

    Pull

    手动镜像：只有你手动点击更新按键时，Gitee 才会从 GitHub 同步仓库。

仓库镜像会同步以下内容：

  • 分支（Branches）
  • 标签（Tags）
  • 提交记录（Commits）

配置仓库镜像可以帮助你管理 GitHub 的仓库，减少维护不同平台仓库的时间成本。

如果你在使用过程中遇到问题，请移步 用户反馈仓库 向我们反馈。

配置仓库镜像

添加 Push 方向的镜像​

Push 方向的镜像用于将 Gitee 的仓库自动镜像到 GitHub 。

配置此镜像后，当你提交代码到 Gitee 的仓库时，Gitee 会自动向 GitHub 同步仓库。

你可以通过以下方式添加 Push 方向的镜像：

  1. 进入需要使用镜像功能的仓库，进入「管理」找到「仓库镜像管理」选项，点击「添加镜像」按键；

    如果你还没有绑定 GitHub 帐号，请根据弹窗提示绑定 GitHub 帐号；

    输入图片说明

  2. 添加镜像；

    输入图片说明

    1. 在「镜像方向」中选择 Push 方向；

    2. 在「镜像仓库」下拉列表中选择需要镜像的仓库；

    3. 在「个人令牌」中输入你的 GitHub 私人令牌；

      • 私人令牌中必须包含对 repo 的访问授权，否则添加后镜像不可用。

    4. 点击「添加」保存镜像配置。

配置完成后，可以通过以下方式触发镜像操作（Gitee 向 GitHub 同步仓库）：

镜像触发的最短间隔时间为 5 分钟。

如果只配置了 Push 方向的镜像，建议将最新的代码提交到 Gitee 仓库；

Gitee 会自动向 GitHub 同步仓库（分支/Branches、标签/Tags、提交记录/Commits）。

添加 Pull 方向的镜像​

Pull 方向的镜像用于将 GitHub 的仓库镜像到 Gitee 。

你可以根据自身需求选择 自动镜像 或 手动镜像。

你可以通过以下方式配置 Pull 方向的镜像：

  1. 进入需要使用镜像功能的仓库，进入「管理」找到「仓库镜像管理」选项，点击「添加镜像」按键；

    如果你还没有绑定 GitHub 帐号，请根据弹窗提示绑定 GitHub 帐号；

    输入图片说明

  2. 添加镜像；

    输入图片说明

    1. 在「镜像方向」中选择 Pull 方向；

    2. 在「镜像仓库」下拉列表中选择需要镜像的仓库；

    3. 在「个人令牌」中输入你的 GitHub 私人令牌；

      • 私人令牌中必须包含对 repo 的访问授权，否则添加后镜像不可用；

    4. 根据自身需求选择是否勾选「自动从 GitHub 同步仓库」；

      • 勾选后，我们将会在镜像仓库中自动生成 webhook 用于实现自动镜像；
      • 此功能需要你的个人令牌中包含对 admin:repo_hook 的访问授权，否则会添加失败；

    5. 点击「添加」保存镜像配置；

      • 如果添加失败，请根据 如何申请 GitHub 私人令牌 提供的流程重新申请私人令牌；
      • 如果重新申请私人令牌后仍然添加失败，请取消勾选「自动从 GitHub 同步仓库」后点击「添加」保存镜像，并 手动配置 webhook。

配置完成后，可以通过以下方式触发镜像操作（Gitee 从 GitHub 同步仓库）：

镜像触发的最短间隔时间为 5 分钟。

如果只配置了 Pull 方向的镜像，建议你将最新的代码提交到 GitHub 镜像仓库；

Gitee 会自动从 GitHub 同步仓库（分支/Branches、标签/Tags、提交记录/Commits）。

双向镜像​

双向镜像指对同一个 GitHub 仓库同时配置了两种镜像。

配置双向镜像后，你在任意一个平台上提交的代码都将被同步到另一个平台。

Note：双向镜像目前存在代码丢失的风险，请谨慎使用！

为避免代码丢失，使用 双向镜像 功能时，请遵循以下规则

  1. 不要同一时间在 Gitee 仓库和 GitHub 镜像仓库提交代码；

  2. 尽量保证 Gitee 仓库和 GitHub 镜像仓库的提交代码间隔时间大于 30 分钟。

管理仓库镜像

注意事项​

使用仓库镜像功能时，请关注以下信息：

  1. 只支持镜像 已绑定 GitHub 帐号授权访问的 仓库；

  2. 更新请求一旦发出，除非 强制停止，否则将无法中断；

  3. 暂时不支持同步 Git-LFS；

  4. 同步时间超过 30 分钟视为超时，大型仓库不建议使用镜像方式同步；

  5. 镜像操作会覆盖目标仓库的分支、标签和提交记录；请注意备份并小心使用。

手动更新​

无论何时，都可以通过使用「仓库镜像管理」页面中的「更新」按键手动发起更新请求。

更新请求一旦发起将无法手动停止，请谨慎操作。

每一个镜像的最短更新时间间隔为 5 分钟。

强制停止​

镜像更新请求发起后，如果连续 5 次镜像失败，镜像操作将被强制停止。

你可以在镜像列表中看到最后一次镜像失败返回的错误信息。

强制停止后，最快可以在 5 分钟后再次发起更新请求。

常见问题

如何申请 GitHub 私人令牌？​

GitHub 私人令牌用于授予 Gitee 读写 Github 仓库的权限。

你可以通过以下方式申请 GitHub 私人令牌：

  1. 登录与 Gitee 绑定的 GitHub 帐号；

  2. 通过路径「用户头像」→「Settings」进入「Developer setting」；

  3. 选择「Personal access tokens」选项后点击「Generate new token」；

4.「Note」字段可以随意填写；例如，Gitee_Mirror；

5.「Select scopes」字段请根据你的需求进行勾选；

  - `repo` 字段为必选字段，请您直接勾选；
  - `admin:repo_hook` 字段为可选字段，用于自动生成 webhook；
    > 当您需要 Gitee 自动从 GitHub 同步仓库时，建议您勾选。

  1. 点击「Generate token」生成私人令牌；

  2. 复制私人令牌并妥善保管。

    私人令牌

为什么推送到 GitHub 会失败？​

如果你的 GitHub 帐号启用了 Keep my email addresses private（对我的电子邮件地址进行保密）功能，且在 Gitee 上使用你的邮箱 push 代码的话，通过 Gitee 推送将会受到该功能限制。

如何手动配置 Webhook？​

Webhook 用于实现 Pull 方向镜像的自动同步。

如果你无法使用我们提供的自动生成 webhook 功能，或者误删了自动生成的 webhook；

你可以通过以下方式手动配置 webhook：

1. 申请 Gitee 的私人令牌​

如果你现有的私人令牌中包含了「project」权限，可以跳过此步骤

  1. 通过路径「用户头像」→「设置」找到「私人令牌」选项；

    私人令牌

  2. 根据以下步骤生成一个私人令牌；

    输入图片说明

    -「私人令牌描述」字段可以随意填写；例如，Gitee_Mirror；

    • 勾选 project 权限；
    • 点击「提交」生成私人令牌；

  3. 复制私人令牌并妥善保管。

2. 配置 webhook​

  1. 进入 GitHub 的镜像仓库中，进入「Setting」找到「Webhooks」选项，点击「Add webhook」；

  2. 按照如下格式填写「Payload URL」字段；

    https://gitee.com/api/v5/repos/:owner/:repo/remote_mirror/pull?access_token=:personal access token
    • :owner：指仓库归属
    • :repo：指仓库名称
    • :personal access token：指你的 Gitee 私人令牌

  3. 选择「Just the push event.」；

    • 需要自定义触发行为时，请选择「Let me select individual events.」后自行定义；

  4. 确保「Active」处于勾选状态后，点击「Add webhook」保存 webhook；

3. Webhook 连通性测试​

保存 webhook 后，GitHub 会自动发送测试请求，可以通过查看列表中 icon 判断 webhook 是否正常工作。

  • 正常：

    正常

  • 不正常：

    不正常

    • 遇到此情况，请仔细检查「Payload URL」是否正确后重试。

常见错误​

  • 未找到此仓库：请检查镜像仓库是否被删除或更改名称。

  • 无效的私人令牌：请检查私人令牌是否输入正确。

  • 无权限的私人令牌：请检查私人令牌是否包含 repo 授权；

  • 仓库正在读写中，请稍后重试：Pull 或 Push 镜像正在更新中，请在更新结束后重试即可。