功能简介
仓库镜像管理功能用于配置和管理仓库镜像;配置仓库镜像可以实现不同平台之间仓库分支、标签和提交信息的自动同步。
目前该功能限时开放至 2022 年 08 月 31 日,在限时开放期结束前,我们将更新相关产品策略。
Gitee 支持设置两种镜像:
-
Push:用于将
Gitee
的仓库自动镜像到GitHub
。配置此镜像后,当你提交代码到 Gitee 的仓库时,Gitee 会自动向 GitHub 同步仓库。
-
Pull:用于将
GitHub
的仓库镜像到Gitee
。你可以根据自身需求选择 自动镜像 或 手动镜像;
自动镜像:当你提交代码到 GitHub 镜像仓库时,Gitee 会自动从 GitHub 同步仓库;
手动镜像:只有你手动点击更新按键时,Gitee 才会从 GitHub 同步仓库。
仓库镜像会同步以下内容:
- 分支(Branches)
- 标签(Tags)
- 提交记录(Commits)
配置仓库镜像可以帮助你管理 GitHub 的仓库,减少维护不同平台仓库的时间成本。
如果你在使用过程中遇到问题,请移步 用户反馈仓库 向我们反馈。
配置仓库镜像
添加 Push 方向的镜像
Push 方向的镜像用于将 Gitee
的仓库自动镜像到 GitHub
。
配置此镜像后,当你提交代码到 Gitee 的仓库时,Gitee 会自动向 GitHub 同步仓库。
你可以通过以下方式添加 Push 方向的镜像:
-
进入需要使用镜像功能的仓库,进入「管理」找到「仓库镜像管理」选项,点击「添加镜像」按键;
如果你还没有绑定 GitHub 帐号,请根据弹窗提示绑定 GitHub 帐号;
-
添加镜像;
-
在「镜像方向」中选择 Push 方向;
-
在「镜像仓库」下拉列表中选择需要镜像的仓库;
-
在「个人令牌」中输入你的 GitHub 私人令牌;
- 私人令牌中必须包含对
repo
的访问授权,否则添加后镜像不可用。
- 私人令牌中必须包含对
-
点击「添加」保存镜像配置。
-
配置完成后,可以通过以下方式触发镜像操作(Gitee 向 GitHub 同步仓库):
- 提交代码到 Gitee 仓库
- 手动更新镜像
镜像触发的最短间隔时间为 5 分钟。
如果只配置了 Push 方向的镜像,建议将最新的代码提交到 Gitee 仓库;
Gitee 会自动向 GitHub 同步仓库(分支/Branches、标签/Tags、提交记录/Commits)。
添加 Pull 方向的镜像
Pull 方向的镜像用于将 GitHub
的仓库镜像到 Gitee
。
你可以根据自身需求选择 自动镜像 或 手动镜像。
你可以通过以下方式配置 Pull 方向的镜像:
-
进入需要使用镜像功能的仓库,进入「管理」找到「仓库镜像管理」选项,点击「添加镜像」按键;
如果你还没有绑定 GitHub 帐号,请根据弹窗提示绑定 GitHub 帐号;
-
添加镜像;
-
在「镜像方向」中选择 Pull 方向;
-
在「镜像仓库」下拉列表中选择需要镜像的仓库;
-
在「个人令牌」中输入你的 GitHub 私人令牌;
- 私人令牌中必须包含对
repo
的访问授权,否则添加后镜像不可用;
- 私人令牌中必须包含对
-
根据自身需求选择是否勾选「自动从 GitHub 同步仓库」;
- 勾选后,我们将会在镜像仓库中自动生成 webhook 用于实现自动镜像;
- 此功能需要你的个人令牌中包含对
admin:repo_hook
的访问授权,否则会添加失败;
-
点击「添加」保存镜像配置;
- 如果添加失败,请根据 如何申请 GitHub 私人令牌 提供的流程重新申请私人令牌;
- 如果重新申请私人令牌后仍然添加失败,请取消勾选「自动从 GitHub 同步仓库」后点击「添加」保存镜像,并 手动配置 webhook。
-
配置完成后,可以通过以下方式触发镜像操作(Gitee 从 GitHub 同步仓库):
- 推送代码到 GitHub 镜像仓库
- 手动更新镜像
镜像触发的最短间隔时间为 5 分钟。
如果只配置了 Pull 方向的镜像,建议你将最新的代码提交到 GitHub 镜像仓库;
Gitee 会自动从 GitHub 同步仓库(分支/Branches、标签/Tags、提交记录/Commits)。
双向镜像
双向镜像指对同一个 GitHub 仓库同时配置了两种镜像。
配置双向镜像后,你在任意一个平台上提交的代码都将被同步到另一个平台。
Note:双向镜像目前存在代码丢失的风险,请谨慎使用!
为避免代码丢失,使用 双向镜像 功能时,请遵循以下规则
-
不要同一时间在 Gitee 仓库和 GitHub 镜像仓库提交代码;
-
尽量保证 Gitee 仓库和 GitHub 镜像仓库的提交代码间隔时间大于 30 分钟。
管理仓库镜像
注意事项
使用仓库镜像功能时,请关注以下信息:
-
只支持镜像 已绑定 GitHub 帐号授权访问的 仓库;
-
更新请求一旦发出,除非 强制停止,否则将无法中断;
-
暂时不支持同步
Git-LFS
; -
同步时间超过 30 分钟视为超时,大型仓库不建议使用镜像方式同步;
-
镜像操作会覆盖目标仓库的分支、标签和提交记录;请注意备份并小心使用。
手动更新
无论何时,都可以通过使用「仓库镜像管理」页面中的「更新」按键手动发起更新请求。
更新请求一旦发起将无法手动停止,请谨慎操作。
每一个镜像的最短更新时间间隔为 5 分钟。
强制停止
镜像更新请求发起后,如果连续 5 次镜像失败,镜像操作将被强制停止。
你可以在镜像列表中看到最后一次镜像失败返回的错误信息。
强制停止后,最快可以在 5 分钟后再次发起更新请求。
常见问题
如何申请 GitHub 私人令牌?
GitHub 私人令牌用于授予 Gitee 读写 Github 仓库的权限。
你可以通过以下方式申请 GitHub 私人令牌:
-
登录与 Gitee 绑定的 GitHub 帐号;
-
通过路径「用户头像」→「Settings」进入「Developer setting」;
-
选择「Personal access tokens」选项后点击「Generate new token」;
-
「Note」字段可以随意填写;例如,Gitee_Mirror;
-
「Select scopes」字段请根据你的需求进行勾选;
repo
字段为必选字段,请您直接勾选;admin:repo_hook
字段为可选字段,用于自动生成 webhook;当您需要 Gitee 自动从 GitHub 同步仓库时,建议您勾选。
-
点击「Generate token」生成私人令牌;
-
复制私人令牌并妥善保管。
![](https://i-blog.csdnimg.cn/blog_migrate/a3657b8d016c66f7ca9c197c5a1b436a.png)
为什么推送到 GitHub 会失败?
如果你的 GitHub 帐号启用了 Keep my email addresses private
(对我的电子邮件地址进行保密)功能,且在 Gitee 上使用你的邮箱 push 代码的话,通过 Gitee 推送将会受到该功能限制。
如何手动配置 Webhook?
Webhook 用于实现 Pull 方向镜像的自动同步。
如果你无法使用我们提供的自动生成 webhook 功能,或者误删了自动生成的 webhook;
你可以通过以下方式手动配置 webhook:
1. 申请 Gitee 的私人令牌
如果你现有的私人令牌中包含了「project」权限,可以跳过此步骤
- 通过路径「用户头像」→「设置」找到「私人令牌」选项;
- 根据以下步骤生成一个私人令牌;
编辑编辑编辑
- 「私人令牌描述」字段可以随意填写;例如,Gitee_Mirror;
- 勾选
project
权限; - 点击「提交」生成私人令牌;
3.复制私人令牌并妥善保管。
2. 配置 webhook
- 进入 GitHub 的镜像仓库中,进入「Setting」找到「Webhooks」选项,点击「Add webhook」;
- 按照如下格式填写「Payload URL」字段;
-
https://gitee.com/api/v5/repos/:owner/:repo/remote_mirror/pull?access_token=:personal access token
:owner
:指仓库归属:repo
:指仓库名称:personal access token
:指你的 Gitee 私人令牌
选择「Just the push event.」;
需要自定义触发行为时,请选择「Let me select individual events.」后自行定义;
正常:
不正常:
遇到此情况,请仔细检查「Payload URL」是否正确后重试。
-
未找到此仓库:请检查镜像仓库是否被删除或更改名称。
-
无效的私人令牌:请检查私人令牌是否输入正确。
-
无权限的私人令牌:请检查私人令牌是否包含
repo
授权; -
仓库正在读写中,请稍后重试:Pull 或 Push 镜像正在更新中,请在更新结束后重试即可。
-
确保「Active」处于勾选状态后,点击「Add webhook」保存 webhook;