Gitee Support Center / detail

    仓库镜像管理 ( Gitee <-> Github 双向同步)

    功能简介

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

    目前该功能限时开放至 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 同步仓库时,建议您勾选。

    6. 点击「Generate token」生成私人令牌;

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

      私人令牌

    为什么推送到 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 镜像正在更新中,请在更新结束后重试即可。

    Search