Gerrit镜像到GitHub Enterprise时git push --mirror推送被拒

核心原因分类及解决方法 #

所有分支、标签被批量拒绝推送，基本都是权限配置、规则拦截、引用异常三类问题，按排查优先级从高到低处理：

• 目标仓库权限或保护规则拦截
  • 先确认当前使用的SSH密钥绑定的账号，对GHE目标仓库拥有管理员权限：git push --mirror会强制覆盖远端所有同名引用、创建新分支标签，普通开发者写入权限无法满足操作要求，权限不足时会直接拒绝所有推送。
  • 检查目标仓库状态：如果仓库被设置为归档状态、组织级只读状态，所有写入操作都会被拦截，需要先在GHE后台取消只读/归档设置。
  • 检查分支、标签保护规则：如果仓库配置了全分支禁止强制推送、标签创建需要审批、禁止直接推送匹配分支的规则，会直接拦截mirror同步操作。可以临时关闭所有保护规则，等迁移完成后再重新恢复配置。
• 本地裸仓库拉取异常
  • 你记录的克隆命令存在拼写错误：git cone --bare是无效命令，正确写法为git clone --bare，如果执行命令时真的输错为cone，根本无法拉取远端仓库内容。能进入对应目录大概率是记录时的笔误，建议删除本地仓库重新拉取全量引用，避免拉取不完整导致推送异常：

    rm -rf gerrit_repo.git
    # 用--mirror参数拉取比普通--bare更全，会同步所有远端引用包括隐藏引用
    git clone --mirror ssh://<gerrit_repo>
    cd gerrit_repo.git
    

  • 排查本地引用合法性：执行git show-ref查看所有本地分支、标签，检查是否存在包含特殊字符（空格、~、^、:、控制字符）的非法引用名，GHE对引用命名有强制规范，不符合规范的引用会被直接拒绝推送。
• Gerrit特殊引用冲突
  Gerrit默认会在refs/changes/命名空间下存储所有代码评审的临时引用，GHE默认不支持这类特殊引用的直接写入，不需要迁移历史评审记录的话，推送时排除这类引用即可：

  git push --mirror ssh://<github_repo> --exclude 'refs/changes/*'
  

精准定位方法 #

如果上述步骤排查完仍然报错，执行带详细日志的推送命令，拿到具体拒绝原因即可直接定位问题，不需要盲目试错：

git push -v --mirror ssh://<github_repo>

常见日志对应问题：

• 日志出现permission denied：对应账号权限不足
• 日志出现protected branch hook declined：分支/标签保护规则拦截
• 日志出现invalid refname：存在不合法的引用名称
• 日志出现repository is archived：目标仓库处于归档只读状态

迁移完成前，可以先推一个测试分支验证链路正常：

git push ssh://<github_repo> <任意本地存在的分支名>:migration-test

测试分支推送成功后再执行全量镜像推送即可。

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