1. 镜像推送被 pre-receive hook declined 拦截的真实场景git push --mirror报pre-receive hook declined是代码仓库迁移和周期性同步里最让人头疼的一类问题。它不像认证失败那样直接告诉你密码错了也不像网络超时那样重试就行而是远端仓库在收到你的推送数据之后由服务端的钩子脚本判定「这批引用不允许写入」然后整批拒绝。你看到的往往是一长串! [remote rejected]每个分支后面都跟着pre-receive hook declined最后error: failed to push some refs to ...。这个报错的核心含义是推送动作本身没问题是远端仓库的策略不允许你推这些引用。常见触发原因有几类。第一类是分支命名被保留比如某些代码托管平台会把cherry-pick、revert这类名字保留为内部用途你镜像过来的仓库里恰好存在同名分支钩子直接拒绝。第二类是目标分支受保护master、main、release/*这些分支不允许强制推送或不允许非管理员推送。第三类是权限不足你的账号对目标仓库只有读权限或者 SSH Key 没有写权限。第四类是镜像推送会带上refs/pull/*、refs/merge-requests/*这类特殊引用而目标平台不允许创建。我遇到过一次很典型的情况用git clone --mirror把源仓库完整镜像下来再git push --mirror推到新仓库结果所有分支全被拒。报错信息里明确提到某个tmp-开头的分支名是平台保留的而这个分支是源仓库里一次未完成合并请求留下的临时分支。源仓库自己不管这些临时分支但目标仓库的钩子会拦截。删掉这个分支之后重新推送问题立刻消失。所以排查思路应该是先看报错里有没有点名具体分支或引用再检查目标仓库的分支保护规则和账号权限最后确认镜像里是否带了不该带的引用。这篇内容会从远端钩子策略、分支保护、权限配置三个方向切入给出可复制的git config和push命令组合并演示如何通过 TaoToken 统一 Key/API 通道验证推送结果目标是一次性定位拒绝原因并完成镜像推送。适合谁看正在做仓库迁移、双仓库周期同步、CI 镜像备份的开发和运维同学。如果你只是偶尔 push 一个分支基本不会碰到这个问题但只要你用--mirror就迟早会遇到。2. TaoToken 统一 Key 通道的前置准备与接入配置在讲推送修复之前先说明为什么这里要引入 TaoToken。镜像推送本身是纯 Git 操作和模型通道没关系。但在实际工程里仓库迁移往往伴随着 CI/CD 流水线重建、自动化脚本改造、以及用 AI 辅助排查报错。TaoToken 提供的是统一 Key 和 API 通道让你在多个模型和工具之间用同一套凭证省去到处配置的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。前置准备分两步。第一步是拿到统一 Key。进入控制台的 API Keys 页面创建密钥地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后复制保存后面所有工具都用这一个 Key。第二步是确认你要接入的工具类型。如果你用的是 Claude Code 这类编码 Agent需要配置 Base URL、Key、Model ID 三件套如果你只是想在脚本里调用模型做报错分析直接用 API 通道即可。对于 Claude Code 的接入配置文件通常放在用户目录下的 settings 文件里。下面是一个可复制的 JSON 片段路径和字段名按实际工具要求填写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的统一Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Codex 类的工具配置写在auth.json里同样是 Base URL、Key、Model ID 三件套{ base_url: https://taotoken.net/api, api_key: sk-你的统一Key, model: gpt-4.1 }Cline 或 MCP 类的工具配置方式类似核心是把请求地址指向统一通道把 Key 填成你创建的那一个。这里要强调Base URL 必须写完整Key 必须和创建时一致Model ID 必须是通道支持的模型名三者缺一不可。很多人接入失败就是因为 Model ID 写了个不存在的名字或者 Base URL 少写了路径。配置完成后你可以用模型对话页面快速验证通道是否通地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果对话能正常返回说明 Key 和通道没问题接下来就可以把精力放回 Git 推送本身。如果你需要长期做编码和 Agent 任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到字段不确定的时候对照文档改。Claude Code 的专项接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。3. 可复制的 git config 与 push 命令组合修复镜像推送现在进入正题。假设你已经用git clone --mirror把源仓库镜像到本地目录名叫repo.git目标仓库地址是gittarget.com:group/repo.git。第一步不是急着 push而是先看清楚本地镜像里到底有哪些引用。cd repo.git git for-each-ref --format%(refname) | sort这条命令会列出所有引用包括refs/heads/*、refs/tags/*以及可能存在的refs/pull/*、refs/merge-requests/*。如果看到refs/pull/或refs/merge-requests/开头的引用这些在目标平台通常不允许创建需要排除。第二步检查目标仓库的分支保护规则。这个在网页端设置里看不同平台位置不同但关键词都是「分支保护」「Protected Branches」「Branch Permissions」。确认你的账号对目标分支有推送权限尤其是master、main、release/*。如果目标仓库要求走合并请求那--mirror的强制推送一定会被拒。第三步配置 Git 的推送行为。下面这组git config可以帮你减少不必要的引用推送git config --local push.default matching git config --local remote.origin.mirror true git config --local http.postBuffer 524288000push.default matching让推送行为和镜像语义一致http.postBuffer调大缓冲区避免大仓库推送时因为缓冲区不足中断。如果你走 SSHhttp.postBuffer不影响但留着无害。第四步用精确的 refspec 推送而不是无脑--mirror。这是解决pre-receive hook declined的关键技巧。--mirror会推送所有引用包括那些目标平台不接受的。改成只推分支和标签git push gittarget.com:group/repo.git \ refs/heads/*:refs/heads/* \ refs/tags/*:refs/tags/*前面的表示允许强制更新镜像场景下必须加。如果你确认某些分支不能推可以进一步收窄git push gittarget.com:group/repo.git \ refs/heads/main:refs/heads/main \ refs/heads/develop:refs/heads/develop \ refs/tags/*:refs/tags/*第五步如果报错点名了某个分支比如tmp-branch-xxxx或cherry-pick先在本地删掉这个引用再推git branch -D tmp-branch-xxxx git push gittarget.com:group/repo.git refs/heads/*:refs/heads/*注意git branch -D删的是本地镜像仓库里的分支引用不影响源仓库。删完之后git for-each-ref再确认一次确保没有残留。第六步如果目标仓库确实需要保留所有分支但平台又保留了某些名字那就只能重命名。比如把cherry-pick改成cherry-pick-backupgit branch -m cherry-pick cherry-pick-backup git push gittarget.com:group/repo.git refs/heads/*:refs/heads/*重命名之后源仓库和目标仓库的分支名会不一致这点要提前和团队确认。如果只是做备份镜像名字不一致通常可以接受如果要做双向同步就得另想办法。第七步把上面的命令固化成脚本。下面是一个可复制的 bash 片段处理单个仓库的镜像推送#!/bin/bash set -euo pipefail SOURCE_REPO$1 TARGET_REPO$2 TMP_DIR/tmp/git_mirror_$(date %s) REPO_NAME$(basename $SOURCE_REPO .git) mkdir -p $TMP_DIR cd $TMP_DIR git clone --mirror $SOURCE_REPO $REPO_NAME cd $REPO_NAME # 删除平台保留的临时分支 for br in $(git for-each-ref --format%(refname:short) refs/heads/ | grep -E ^(tmp-|cherry-pick$|revert$)); do echo 删除保留分支: $br git branch -D $br done # 精确推送分支和标签 git push $TARGET_REPO \ refs/heads/*:refs/heads/* \ refs/tags/*:refs/tags/* cd $TMP_DIR rm -rf $REPO_NAME echo 镜像推送完成: $REPO_NAME这个脚本比原始版本多了两个关键点一是主动清理保留分支二是用精确 refspec 代替--mirror。实测下来这两步能解决大部分pre-receive hook declined。4. 验证推送请求与成功结果推送命令执行后怎么确认真的成功了不能只看终端没报错因为有些平台会返回部分成功。下面几个验证步骤建议都做一遍。第一步看推送输出。成功的输出长这样Enumerating objects: 1234, done. Counting objects: 100% (1234/1234), done. Delta compression using up to 8 threads Compressing objects: 100% (800/800), done. Writing objects: 100% (1234/1234), 2.5 MiB | 3.2 MiB/s, done. Total 1234 (delta 400), reused 1000 (delta 300) remote: Resolving deltas: 100% (400/400), done. To gittarget.com:group/repo.git * [new branch] main - main * [new branch] develop - develop * [new tag] v1.0.0 - v1.0.0如果看到[new branch]或[updated]说明引用写入成功。如果看到! [remote rejected]说明还有引用被拒需要回到上一步继续排查。第二步在目标仓库端验证引用。最直接的方式是重新克隆一个裸仓库对比引用列表git clone --mirror gittarget.com:group/repo.git /tmp/verify.git cd /tmp/verify.git git for-each-ref --format%(refname) | sort /tmp/target_refs.txt然后在本地镜像仓库里生成源引用列表cd /path/to/repo.git git for-each-ref --format%(refname) | sort /tmp/source_refs.txt对比两个文件diff /tmp/source_refs.txt /tmp/target_refs.txt如果没有输出说明引用完全一致镜像成功。如果有差异差异行就是没推上去的引用针对性处理。第三步验证提交内容。引用一致不代表提交对象完整可以抽查一个分支的 HEADgit ls-remote gittarget.com:group/repo.git refs/heads/main把返回的 commit hash 和源仓库对比git rev-parse refs/heads/main两个 hash 一致说明该分支的提交对象完整推送。第四步用 TaoToken 通道做辅助验证。如果你在 CI 脚本里集成了模型调用可以让模型帮你分析推送日志。比如把推送输出贴给模型问「这批引用里哪些被拒了可能原因是什么」。模型对话入口是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。这一步不是必须的但在批量迁移几十个仓库时用模型快速归类报错能省不少时间。第五步检查目标仓库的钩子日志。有些平台会在服务端记录pre-receive钩子的拒绝原因位置在仓库设置或管理后台的日志里。如果终端输出不够详细去这里看原始拒绝信息通常能直接看到是哪个规则触发的。第六步确认标签也推上去了。很多人只检查分支忘了标签。git ls-remote --tags可以列出远端所有标签git ls-remote --tags gittarget.com:group/repo.git对比源仓库的标签列表数量一致才算完整。5. 本篇常见报错排查对照这一节把镜像推送过程中最常见的报错列出来对照着排查。报错一pre-receive hook declined且点名cherry-pick或revertremote: The keywords cherry-pick and revert are branch names reserved by CodeHub remote: You are not allowed to create. ! [remote rejected] cherry-pick - cherry-pick (pre-receive hook declined)原因目标平台保留了这些分支名。解决本地删除或重命名该分支再推。git branch -D cherry-pick git push gittarget.com:group/repo.git refs/heads/*:refs/heads/*报错二pre-receive hook declined且点名master或main! [remote rejected] main - main (pre-receive hook declined)原因目标分支受保护不允许强制推送。解决在目标仓库设置里临时关闭分支保护或者用有权限的账号推送。如果平台要求走合并请求那--mirror本身就不适用需要改用普通 push 加 PR 流程。报错三remote: You are not allowed to push code to this projectremote: You are not allowed to push code to this project. fatal: unable to access ...: The requested URL returned error: 403原因账号权限不足。解决确认 SSH Key 已添加到目标平台账号且该账号对目标仓库有写权限。如果是 HTTPS检查 token 是否过期。报错四local proxy failed或连接超时fatal: unable to access ...: Failed to connect to ... port 443: Connection timed out原因网络不通或地址写错。解决检查目标仓库地址是否正确确认当前网络能访问目标平台。注意这里不涉及任何网络工具纯粹是地址和网络连通性问题。报错五error: cannot spawn git: No such file or directory原因Git 环境变量或 PATH 配置有问题。解决确认git --version能正常输出检查脚本里的 Git 路径。报错六reading choices相关错误如果你在 CI 里用模型辅助分析日志偶尔会看到reading choices之类的返回解析错误。这通常是模型响应格式和脚本预期不一致导致的。解决检查 API 返回的 JSON 结构确认解析字段名正确。TaoToken 的接入文档里有返回格式说明对照 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 调整。报错七OAuth相关认证失败remote: OAuth authentication failed原因凭证过期或权限范围不足。解决重新生成 token 或重新授权。如果是 SSH检查 Key 是否被平台吊销。报错八推送大仓库时中断error: RPC failed; HTTP 500 curl 22 The requested URL returned error: 500原因仓库太大单次推送超时或缓冲区不足。解决调大http.postBuffer或者分批推送分支。git config --local http.postBuffer 1048576000 git push gittarget.com:group/repo.git refs/heads/main:refs/heads/main报错九refs/pull/*被拒! [remote rejected] refs/pull/1/head - refs/pull/1/head (pre-receive hook declined)原因镜像里带了平台特有的 pull 引用。解决不要用--mirror改用精确 refspec 只推分支和标签。报错十deny updating a hidden ref原因推送了隐藏引用。解决同样改用精确 refspec排除refs/pull/*和refs/merge-requests/*。排查顺序建议先看报错点名了哪个引用再查目标仓库的保护规则和权限最后检查本地镜像的引用列表。大部分问题在前两步就能定位。6. 长期镜像同步的工程化建议与通道选择单次修复解决的是眼前问题但如果你要做的是周期性同步比如每天或每小时把源仓库镜像到目标仓库那就需要工程化处理。下面几条是实际踩过坑之后总结的建议。第一不要用--mirror做周期性推送。--mirror的语义是「让目标仓库和源仓库完全一致」包括删除目标仓库里源仓库没有的引用。这在首次迁移时有用但周期性同步时很危险一旦源仓库临时删了个分支目标仓库也会跟着删。改用精确 refspec只推分支和标签不删远端。第二把保留分支的清理逻辑固化到脚本里。不同平台的保留分支名不一样但常见的就那么几个cherry-pick、revert、tmp-*、temp-*。在 clone 之后、push 之前统一过滤一遍。第三给推送加超时和重试。大仓库推送偶尔会因为网络抖动中断脚本里加个重试逻辑for i in 1 2 3; do if git push $TARGET_REPO refs/heads/*:refs/heads/* refs/tags/*:refs/tags/*; then break fi echo 推送失败第 $i 次重试... sleep 5 done第四记录每次同步的引用差异。同步完成后对比源和目标引用列表把差异写进日志。这样出问题时能快速定位是哪个分支没同步。第五如果同步任务里需要模型辅助分析日志或生成报告用统一 Key 通道能省去多套凭证管理。Coding Plan 适合长期跑 Agent 任务的场景地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。API Keys 管理入口在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。第六目标仓库的分支保护规则要提前和团队对齐。如果目标仓库要求所有变更走合并请求那镜像推送这条路本身就走不通需要改用「推送特性分支 自动创建 PR」的方案。这个决策要在迁移开始前定好不要等推送被拒了才发现。最后说一个实际经验镜像推送失败时终端输出往往只给一行pre-receive hook declined真正的拒绝原因在服务端钩子日志里。如果平台不暴露钩子日志就靠报错里点名的引用反推。大多数情况下报错里提到的那个分支名就是问题所在。删掉它或者重命名它再推一次问题就解决了。