跳到主要内容

功能简介

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

目前该功能限时开放至 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 镜像正在更新中,请在更新结束后重试即可。