无法将GitLab仓库镜像推送到GitHub报GH003错误如何解决

报错根因 #

该报错由GitHub目标仓库的分支保护规则触发：git push --mirror命令默认携带强制推送逻辑，而大部分GitHub仓库会默认给master、develop这类核心分支开启强制推送拦截，即便是仓库管理员也会被默认拦截，因此出现pre-receive hook declined的报错。

解决方案 #

方案1：临时关闭分支保护规则（全量镜像同步推荐） #

适合首次全量镜像同步的场景，同步完成后可还原规则保证分支安全：

• 进入GitHub目标仓库的「设置」页面
• 在左侧菜单栏找到「代码和自动化」分类下的「分支」选项
• 找到「分支保护规则」板块，点击master、develop分支对应规则右侧的「编辑」按钮
• 取消勾选「阻止强制推送」选项，同时取消勾选「不允许绕过上述设置」的开关，保存修改
• 重新执行镜像推送命令：

git push --mirror https://github.***.com/***/***.git

• 同步完成后回到分支保护规则页面，还原之前的配置即可。

方案2：添加同步账号到分支保护白名单（定期同步推荐） #

如果需要长期定期做镜像同步，不需要每次修改规则：

• 同样进入分支保护规则的编辑页面
• 找到「允许强制推送」的配置项，选择「允许指定用户和组织」，把你用于同步的GitHub账号添加到白名单中
• 同时可以添加「允许指定角色绕过必要的拉取请求」的权限，避免其他保护规则拦截同步操作
• 配置完成后，该账号执行镜像推送命令不会再被拦截。

方案3：替换为非强制同步方式（不想改保护规则时可用） #

如果不希望改动现有分支保护配置，可以放弃--mirror的全量强制同步逻辑，改为按需推送分支：

• 先给本地仓库添加GitHub远端地址：

git remote add github https://github.***.com/***/***.git

• 拉取GitHub远端最新代码避免冲突：

git fetch github

• 逐个推送需要同步的分支和标签：

git push github master
git push github develop
git push github --tags

内容的提问来源于stack exchange，提问作者Ragini