仓库镜像同步怎么配，推送和拉取的边界要分清
仓库镜像同步怎么配，推送和拉取的边界要分清
定义框：代码仓库镜像，指在极狐GitLab 仓库与外部 Git 托管位置之间自动同步分支、标签和提交的机制。分三种方向——推送镜像（把极狐GitLab 的提交复制到外部仓库）、拉取镜像（定时从外部仓库拉取更新到极狐GitLab）、双向镜像（可用，但官方明确提示可能导致冲突，一般不建议）。推送镜像基础版即可用；拉取镜像需要专业版或旗舰版。
为什么需要镜像同步
仓库镜像不是为了"备份"这一个场景，它在工程实践里至少覆盖三类真实需求：
迁移过渡期。项目规范仓库已经迁到极狐GitLab，但旧托管地还有下游系统、CI 钩子或外部协作者在拉代码。这时配一个推送镜像，极狐GitLab 每次收到推送，旧位置在五分钟内同步收到副本（如果开启了"仅镜像受保护分支"，则一分钟内），迁移期不用改任何下游配置。
对外开源镜像。私有化实例上的项目想开源一份只读副本，推送到公共托管地即可，主仓库权限模型不受影响。
规范仓库在别处。团队整体迁到了极狐GitLab，但个别项目的上游还在外部，配拉取镜像，把上游的提交、标签、分支定期拉到极狐GitLab 里参与内网流水线。
先分清一个关键差异：推送镜像是被动的，只有上游收到推送或管理员强制更新时才同步；拉取镜像是主动轮询的，上次拉取 30 分钟后自动再次拉取，且这个自动轮询无法禁用。
怎么配，两条链路分开走
链路一，配置推送镜像
前置条件：你对项目有维护者或所有者角色；仓库和远程仓库对象格式一致（SHA-1 与 SHA-256 仓库之间不能镜像）。
操作路径：项目左侧栏 设置 → 代码仓库 → 展开镜像代码仓库，输入 Git 仓库 URL（支持 http://、https://、ssh://、git://），镜像方向选"推送"，选择认证方法后保存。
以同步到海外某 Git 托管平台为例，认证推荐用细粒度个人访问令牌，只授予"代码仓库内容"读写权限：
Git 仓库 URL: https://github.example.com/GROUP/PROJECT.git
用户名: 令牌所有者的用户名
密码: 细粒度个人访问令牌（不要用账号密码）如果仓库里有 .github/workflows 目录，令牌还要额外授予 Workflows 读写权限，否则推送会被对端拒绝。
用 SSH 认证时，极狐GitLab 会为你的仓库生成一个公钥，需要把它部署到对端服务器；同时建议用"检测主机密钥"功能让极狐GitLab 抓取并显示指纹。镜像时极狐GitLab 会在连接前确认至少一个存储的主机密钥匹配，防止恶意代码注入或凭据被盗。
创建后可以限制同步范围：勾选"仅镜像受保护分支"，或用正则表达式镜像特定分支。
链路二，配置拉取镜像
镜像方向选"拉取"，认证后按需勾选三个选项：
覆盖已分歧的分支：默认关闭。开启后本地与上游分歧的分支会被强制对齐，本地改动会丢失，慎用。
为镜像更新触发流水线：镜像更新时自动跑流水线。注意它使用创建镜像用户的凭据，只应为自己完全信任的项目开启。
仅镜像受保护的分支。
拉取的触发方式有三种：30 分钟自动轮询（不可禁用）、管理员强制更新、API 主动通知：
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/projects/<project_id>/mirror/pull"注意 API 触发同样受默认 5 分钟最小拉取间隔限制（私有化部署实例上可配置），别指望靠 API 调用把同步压到秒级。
三个高频踩坑，出问题先查这里
踩坑一，远程分支被静默覆盖。 推送镜像默认行为是：如果远程镜像上的引用与本地分歧，下次推送会直接覆盖远程，远程上多出来的提交会丢失。如果对端确实有人直接提交，创建镜像时要勾选"保留分歧的引用"——分歧分支的更新会被跳过并标记为失败，而不是覆盖。注意这个选项创建后只能通过远程镜像 API 修改。
踩坑二，拉取镜像悄悄停摆。 拉取更新失败会自动重试，连续失败 14 次后镜像被标记为硬失败，不再入队更新，只在项目仪表板和拉取镜像设置页能看到。长时间网络中断后可能一批项目集体停摆，需要管理员强制更新恢复。
踩坑三，以为删了分支就干净了。 拉取镜像里，仅在下游仓库删除、上游仍存在的分支，下次拉取会重新出现；而推送镜像里，合并进默认分支后删除的分支，会在下次推送时从远程镜像删除。两个方向的删除语义完全不同，清理脚本写反了会反复"复活"分支。
另外两条边界提前记住：每个项目最多 10 个已启用的推送镜像；群组启用 SSO 强制时，创建镜像的用户必须保持有效 SSO 会话，否则镜像失败——想摆脱会话依赖，改用项目访问令牌或群组访问令牌配服务账号。
常见问题
Q：推送和拉取能配在同一个仓库上吗？
技术上可以组成双向镜像，但官方文档明确提示可能导致冲突，两个方向同时写同一批分支时尤其危险。确有双写需求时，至少用"仅镜像受保护分支"或正则把两边的写入范围切开。
Q：镜像和流水线有什么联动？
拉取镜像可勾选"为镜像更新触发流水线"，上游更新即自动构建。评估 Runner 负载之余，更要评估凭据风险——流水线以创建镜像用户的身份运行，不受信任的上游配合恶意维护者可能借此获取 CI/CD 变量值。
Q：镜像失败排查看哪里？
先看项目"镜像仓库"设置区的错误信息，分歧分支会在这里报错；拉取镜像长期失败看是否已硬失败（连续 14 次）；推送镜像确认对端认证是否过期，令牌轮换后镜像里存的旧凭据不会自动更新。
结语
仓库镜像的配置入口只有一屏，真正决定成败的是方向语义（被动推送 vs 主动轮询）、分歧处理策略和凭据生命周期这三件事。迁移期把它当过渡桥，稳态下把它当单向分发通道，能避开绝大多数事故。
想系统了解极狐GitLab 的代码托管与迁移能力，可以访问极狐GitLab 官网，或阅读官方文档中仓库镜像的完整说明。如果你们正在做多平台仓库同步或迁移评估，也欢迎在官网预约演示，看看镜像能力如何嵌进现有交付链路。
