1. 一次 git push 被拒的完整现场git push敲下去终端刷出一行红字! [remote rejected] main - main (pre-receive hook declined)紧接着error: failed to push some refs to ...。这个报错在 GitLab、Gitea、GitHub 自建等平台上都很常见字面意思是「服务端的 pre-receive 钩子拒绝了这次推送」但真正的原因往往不在钩子本身而在分支保护规则、账号权限、或者本地配置和远端对不上。它适合谁看适合正在往团队仓库推代码、被remote rejected卡住、又不想盲目--force把别人代码冲掉的开发者。这篇会从报错定位讲到修复覆盖 Protected branches 权限、分支保护规则、本地config.toml/settings.json骨架以及逐条验证命令。我试过在同一个仓库里同时踩到「分支被保护」和「本地 remote 指向错」两个坑所以下面把排查顺序也一并给你。先说结论方向pre-receive hook declined是服务端在收到你的推送后、真正写入引用前执行的校验失败。它可能是分支保护、可能是提交者邮箱不匹配、可能是钩子脚本自定义规则、也可能是你根本没有该分支的写权限。定位思路是「先看服务端规则再看本地配置最后看提交内容」。2. TaoToken 统一 Key 在推送链路里的位置很多同学会疑惑Git 推送和 TaoToken 有什么关系关系在于当你的开发流程里用到了 AI 辅助编码、代码审查、或者 CI 里调用模型做 commit message 生成、diff 摘要时这些环节通常需要一个统一的模型访问入口。TaoToken 提供的就是这样一个统一 Key 的接入层官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是你用一把 Key就能在本地脚本、CI 流水线、编辑器插件里调用不同模型不用为每个工具单独配一套凭证。对于「推送被拒」这个场景它的价值体现在两处一是你可以在推送前用脚本自动生成规范的 commit message减少因提交信息不合规被钩子拒绝的概率二是 CI 里可以用它做推送后的自动检查。适合经常写自动化脚本、又不想管理一堆 Key 的开发者。需要说清楚的是TaoToken 不是 Git 托管平台它不负责你的仓库权限。pre-receive hook declined的根因还是在 Git 服务端的规则上TaoToken 只是帮你把「推送前后的辅助流程」串起来。把这两件事分清楚排查才不会跑偏。3. 可复制的配置骨架与逐条验证命令3.1 先确认远端和分支状态排查第一步永远是看清楚现状别急着改规则。下面这几条命令按顺序执行# 查看当前远端地址确认推的是不是你以为的那个仓库 git remote -v # 查看当前分支和跟踪关系 git branch -vv # 查看本地领先/落后远端多少 git status -sb # 拉取远端最新引用但不合并看远端到底有哪些分支 git fetch origin --prune git branch -r如果git remote -v里的地址指向了一个你没有写权限的仓库那pre-receive hook declined只是表象真正问题是推错了地方。这种情况改 remote 即可git remote set-url origin gityour-git-host:group/repo.git3.2 分支保护规则检查服务端pre-receive hook declined最常见的原因就是目标分支被保护。以 GitLab 为例路径是Settings - Repository - Protected branches找到main或master看Allowed to push这一栏是不是No one或者只允许 Maintainer。如果你只是 Developer 角色推送就会被钩子挡下。修复方式有两种。第一种是临时解除保护在 Protected branches 页面点Unprotect推完再重新保护。第二种是更规范的做法——不要直接推main而是推一个特性分支再走合并请求# 从当前改动创建特性分支 git checkout -b feature/fix-push-issue # 推特性分支通常不受 main 保护规则限制 git push -u origin feature/fix-push-issue注意git push -uf origin main这种强制推送能绕过一部分本地冲突但绕不过服务端保护规则而且会覆盖远端历史。除非你确认这是个人仓库且没有协作者否则不要用。3.3 本地配置骨架config.toml如果你在用脚本或工具链管理多个仓库的推送行为可以用一个config.toml把远端、分支、钩子检查项集中管理。下面是一个可复制的骨架# config.toml - 仓库推送与检查配置骨架 [repo] name my-project remote origin default_branch main protected_branches [main, release/*] [push] # 推送前是否自动拉取 auto_fetch true # 禁止对保护分支强制推送 allow_force_on_protected false # 推送前检查提交信息格式 check_commit_message true [commit] # 提交信息正则不符合则本地拦截 message_pattern ^(feat|fix|docs|refactor|test|chore)(\\(.\\))?: .{1,72}$ [taotoken] # 统一 Key 的接入地址用于推送前后辅助流程 api_base https://taotoken.net/api # Key 从环境变量读取不要硬编码进仓库 api_key_env TAOTOKEN_API_KEY这个骨架的用法是在推送前跑一个校验脚本读config.toml检查当前分支是否在protected_branches里、提交信息是否符合message_pattern。不符合就在本地拦下避免推到远端才被钩子拒绝。3.4 本地配置骨架settings.json如果你用的是 VS Code 或类似编辑器可以把推送相关的设置放进settings.json{ git.enableSmartCommit: false, git.confirmSync: true, git.autofetch: true, git.branchProtection: [main, release/*], git.branchProtectionPrompt: alwaysCommitToNewBranch, git.allowForcePush: false, git.pushTags: false }git.branchProtection会在你试图直接提交到main时弹窗提醒git.branchProtectionPrompt设为alwaysCommitToNewBranch会引导你新建分支。这套配置配合服务端的 Protected branches能从本地就减少被pre-receive hook declined的概率。3.5 提交者身份检查有些服务端的 pre-receive 钩子会校验提交者邮箱是否属于该账号。检查本地配置git config user.name git config user.email # 查看最近几条提交的作者信息 git log -3 --prettyformat:%h %an %ae %s如果邮箱和你在 Git 平台注册的不一致钩子可能直接拒绝。修正方式git config --global user.email youexample.com git config --global user.name Your Name # 如果最近一次提交作者错了可以修正后重新提交 git commit --amend --reset-author --no-edit4. 验证请求与成功结果改完配置后别直接推main先用一条「只验证不写入」的命令确认连通性和权限# 干跑只显示将要推送的引用不实际写入 git push --dry-run origin main如果--dry-run也报pre-receive hook declined说明服务端规则仍然拦着回到 3.2 检查保护分支。如果--dry-run通过再正式推# 推特性分支推荐路径 git push -u origin feature/fix-push-issue # 或者确认有权限后推 main git push origin main成功时终端会显示类似Enumerating objects: 12, done. Counting objects: 100% (12/12), done. Writing objects: 100% (7/7), 1.2 KiB | 1.2 MiB/s, done. To gityour-git-host:group/repo.git a1b2c3d..e4f5g6h feature/fix-push-issue - feature/fix-push-issue看到-后面的分支名和done就说明推送成功。如果这时你想用 TaoToken 的模型对话能力确认一下提交内容是否规范可以走模型对话入口 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 把 diff 贴进去让它帮你生成 commit message。5. 本篇常见错排查5.1 报错依旧Protected branches 没改对很多人点了Unprotect还是被拒原因是保护规则可能配在通配分支上比如release/*或*。回到Settings - Repository - Protected branches把所有匹配当前分支的规则都检查一遍。另外有些平台有「默认分支保护」的全局设置需要到组织级别去看。5.2 报错变成failed to push some refs如果pre-receive hook declined消失了但出现failed to push some refs通常是本地落后远端。先拉再推git pull --rebase origin main git push origin main--rebase比默认 merge 更干净能避免多出一条无意义的合并提交。5.3 提交信息被钩子拒绝如果钩子校验 commit message 格式而你写的是「update」这种会被拒。用git commit --amend改最近一条或者git rebase -i批量改# 修改最近一条提交信息 git commit --amend -m fix: 修复推送被 pre-receive hook 拒绝的问题5.4 权限不足Developer 推不了保护分支这是角色问题不是配置问题。让仓库 Maintainer 在Settings - Members里把你的角色提到 Maintainer或者走合并请求流程。别试图用--force硬推服务端钩子会直接挡下。5.5 本地 remote 指向了 fork 而非主仓库git remote -v如果显示的是你自己的 fork而你想推主仓库需要加一个 upstreamgit remote add upstream gityour-git-host:group/repo.git git push upstream feature/fix-push-issue6. 把推送流程固化下来排查完这一次建议把规则固化避免下次再被同一个钩子拦。核心动作有三个本地用config.toml或settings.json做提交信息校验和分支保护提醒推送前统一跑git push --dry-run长期在团队里做编码和 Agent 自动化的可以走 Coding Plan 入口 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 把模型调用和推送检查串进流水线。如果你需要管理多把 Key 或查看调用额度控制台在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite Key 的创建和管理在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入细节和参数说明看文档 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite Claude Code 相关的接入参考 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后留一个我踩过的坑pre-receive hook declined有时候和你的代码一点关系都没有纯粹是服务端钩子脚本里写死了「禁止直接推 main」。这种情况下最省事的做法不是去改钩子而是老老实实开特性分支走 MR。把这条当成团队规范比每次和钩子较劲划算得多。
