1. 从一次真实的 push 被拒说起
你敲下git push origin dev，终端没有像往常一样滚动出Writing objects的进度条，而是干脆利落地甩回一段红字：
! [remote rejected] dev -> dev (pre-receive hook declined) error: failed to push some refs to 'git@your-gitlab.com:team/project.git'pre-receive hook declined这个报错，字面意思是「服务端的 pre-receive 钩子拒绝了这次推送」。它和本地代码写错、网络断连完全不是一回事——你的 commit 已经成功打包并传到了远端，是远端在「入库前最后一道闸门」把你拦下来了。换句话说，问题不在你的电脑上，而在仓库的服务端规则里。
这个场景在团队里特别常见：公司 GitLab 迁移、仓库地址换了、新项目默认开了分支保护、或者 CI 流水线加了提交信息校验。很多人第一反应是「我是不是没权限」，然后开始怀疑 SSH key、怀疑账号，其实方向跑偏了。这篇就按我实际排查的顺序，把pre-receive hook declined从定位到修复讲清楚，同时给出一份可复制的settings.json配置骨架，以及逐条验证动作，让你改完能立刻确认是否真的通了。
适合谁看：正在被这个报错卡住的开发、刚接手仓库配置的维护者、以及想搞清楚「服务端钩子到底管什么」的同学。读完你应该能自己判断：这次拒绝是分支保护、提交信息规范、还是钩子脚本本身的问题。
2. 先搞清楚 pre-receive hook 到底在拦什么
要排查，先得知道这道闸门的工作机制。Git 服务端在接收推送时，会依次触发几个钩子，pre-receive是最早执行的那个，它在任何 ref 被更新之前运行，接收标准输入里的一批旧SHA 新SHA refname记录。只要这个脚本以非零状态退出，整批推送全部回滚，客户端看到的就是pre-receive hook declined。
所以它拦你的原因，通常落在下面几类：
| 拦截类型 | 典型表现 | 谁在管 |
|---|---|---|
| 分支保护 | dev/main 被设为 protected，developer 无权直推 | 仓库 Maintainer |
| 提交信息规范 | commit message 不符合feat: xxx之类格式 | 服务端钩子脚本 |
| 权限角色不足 | 你的角色低于推送所需级别 | 项目管理员 |
| 钩子脚本自定义校验 | 文件大小、密钥扫描、禁止某些路径 | CI/运维 |
| 仓库迁移后规则残留 | 新地址沿用了旧的保护策略 | 迁移负责人 |
关键点在于：报错信息本身不会告诉你具体是哪一条规则拦的。GitLab 出于安全考虑，通常只回一句pre-receive hook declined，真正的拒绝原因写在服务端的钩子日志里。这就是为什么很多人卡在这里——客户端看不到细节，只能靠排除法。
我一般的排查顺序是：先确认分支保护，再确认提交信息，最后才怀疑钩子脚本。因为前两个是最高频的原因，而且都能在网页端自助确认。
3. TaoToken 前置：把模型对话和配置管理接进来
排查这类问题时，我习惯把「查规则」和「问模型」两条线并行。查规则靠 GitLab 网页端，问模型则用来快速理解钩子脚本逻辑、生成规范的 commit message、或者让模型帮我读一段看不懂的 CI 配置。这里就用 TaoToken 来做这件事，它提供统一的模型对话入口和 API，配置一次就能在多个工具里复用。
TaoToken 官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （这个不加 UTM）。你可以先注册拿到 API Key，后面settings.json里要用。
拿 Key 的路径很直接：进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 创建一个新 Key，复制保存。这个 Key 就是后面配置里的凭证。
如果你只是想先验证模型能不能用，可以直接打开模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 试一句「帮我写一个符合 Conventional Commits 的提交信息」，确认返回正常再往下配。
需要说明的是，TaoToken 在这里扮演的是「模型能力入口」的角色，它不替代你的 Git 客户端，也不碰你的仓库。排查 push 报错的主体动作还是在 Git 和 GitLab 上，TaoToken 负责的是辅助理解规则、生成规范提交、以及后续接入编码工具。
4. 可复制的 settings.json 配置骨架
下面这份settings.json骨架，是我在把 TaoToken 接入本地工具链时用的结构。它把 API 地址、Key、默认模型都集中管理，避免每个工具各配一遍。你可以直接复制，把YOUR_API_KEY换成上一步拿到的真实 Key。
{ "provider": { "name": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "YOUR_API_KEY", "timeout": 60000 }, "models": { "default": "claude-sonnet", "fallback": "gpt-4o-mini" }, "features": { "commitMessageAssist": true, "hookLogExplain": true }, "git": { "defaultBranch": "dev", "commitConvention": "conventional" } }几个字段说明一下。baseUrl固定填https://taotoken.net/api，不要带路径后缀。apiKey就是控制台里创建的那串。timeout给 60 秒，模型响应偶尔慢，别设太短。models.default按你实际可用的模型名填，不确定就先在模型对话页面确认。git.commitConvention设成conventional后，配合工具生成的提交信息会默认走feat:、fix:这类前缀，正好能避开很多服务端钩子的格式校验。
如果你用的是 Claude Code 这类编码工具，接入方式略有不同，可以参考文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里的说明，Claude Code 专用入口在 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。长期做编码和 Agent 任务的，可以看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，按套餐走比单次调用更划算。
配置写完后，先别急着 push，用下面这条命令验证配置是否生效：
curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" | head -c 500返回里能看到模型列表，就说明 Key 和地址都对。这一步过了，再回到 Git 排查主线。
5. 逐条验证动作：从分支保护到提交信息
现在进入正题，按顺序做下面这几步，每步都有明确的「通过标准」，做完你就知道卡在哪。
5.1 确认 dev 分支是否被保护
打开 GitLab 仓库页面，进入Settings -> Repository -> Protected branches。看dev是否在列表里，以及Allowed to push这一列写的是谁。如果显示No one或者只有Maintainers，而你的角色是Developer，那基本就是它了。
验证动作：让管理员把dev的Allowed to push改成Developers + Maintainers，或者临时Unprotect。改完立刻重试 push。
git push origin dev通过标准：不再出现pre-receive hook declined，而是正常输出To git@...和分支更新信息。
5.2 确认你的角色级别
进入Settings -> Members，找到你自己的账号，看角色是Guest、Reporter、Developer还是Maintainer。直推受保护分支通常需要Maintainer及以上，或者该分支明确放开了Developer推送。
验证动作：如果角色不够，让管理员升到Maintainer，或者按 5.1 放开分支权限。这一步和 5.1 是配套的，只改一个可能还是不通。
5.3 检查提交信息是否符合钩子规范
很多团队的服务端钩子会校验 commit message 格式，比如必须带 Jira 单号、必须用feat/fix/docs前缀。如果你的提交信息是随手写的「改了一下」，就会被拦。
验证动作：先看最近一条提交信息。
git log -1 --pretty=format:"%s"如果格式明显不规范，用git commit --amend改掉再推：
git commit --amend -m "feat(dev): 修复登录接口参数校验" git push origin dev通过标准：push 成功，且服务端没有再报钩子拒绝。这里就可以用上第 3 节的 TaoToken，让模型按 Conventional Commits 帮你生成一条合规信息，省得反复试。
5.4 查看服务端钩子日志
如果前三步都排除了，问题可能在自定义钩子脚本。GitLab 的钩子日志一般在服务端/var/log/gitlab/gitlab-shell/或仓库的hooks目录下，具体路径取决于部署方式。这部分通常需要运维或管理员权限。
验证动作：让管理员执行下面命令，看最近的拒绝记录。
sudo tail -n 100 /var/log/gitlab/gitlab-shell/gitlab-shell.log通过标准：日志里能看到具体的拒绝原因，比如commit message does not match pattern或file size exceeds limit，按提示修正即可。
5.5 用最小改动复现验证
为了确认修复真的生效，建议用一个无害的小改动做验证，而不是拿一堆未提交的代码去试。
echo "# verify" >> README.md git add README.md git commit -m "docs: 验证 dev 分支推送权限" git push origin dev通过标准：这次 push 成功，说明规则已经放开。确认后可以把这条验证提交 revert 掉，保持历史干净。
6. 本篇常见错排查
排查过程中，有几个坑我踩过，也见别人踩过，单独拎出来说。
误以为是 SSH key 问题。pre-receive hook declined和认证失败是两码事。认证失败报的是Permission denied (publickey)，而钩子拒绝说明你已经通过认证、成功连上服务端了。别去重新生成 SSH key，浪费时间。
只改了分支保护，没改角色。有些人让管理员Unprotect了 dev，但自己角色还是Guest，照样推不上去。分支权限和角色权限要同时满足。
提交信息改了但没 amend。用git commit -m新提交一条，结果要推的是之前那条不合规的 commit，还是被拦。记住pre-receive校验的是本次推送涉及的所有 commit，不是只有最新一条。用git rebase -i或git commit --amend把历史里的问题提交一起修掉。
迁移后规则残留。公司 GitLab 迁移时，新仓库可能继承了旧的保护策略，或者钩子脚本路径没更新导致误判。这种情况让迁移负责人核对一遍Protected branches和hooks目录。
钩子脚本报错但日志没开。有些自建 GitLab 没配钩子日志，拒绝原因查不到。可以让管理员临时在钩子脚本里加一行echo "$refname" >> /tmp/hook.log做调试，定位完再删掉。
用错分支名。本地分支叫dev，远端可能叫develop，或者你推的是dev但保护的是dev/*通配。用git branch -r确认远端分支名，别想当然。
7. 把配置和验证动作固化下来
排查完这一次，更重要的是别下次再从头来一遍。我的做法是把第 4 节的settings.json存进项目根目录的.config/下，配合.gitignore排除真实 Key，团队里共享一份模板。这样新同学入职，复制模板、填自己的 Key，就能直接用模型辅助生成合规提交信息，从源头减少被钩子拦的概率。
对于长期做编码和 Agent 任务的团队，建议直接走 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，把模型调用额度固定下来，不用每次临时申请。接入细节看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Key 管理在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。验证模型是否可用，随时开模型对话 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 试一句就行。
最后留一个我常用的自检清单，push 被拒时按顺序过一遍：分支保护开了吗、角色够吗、提交信息合规吗、钩子日志看了吗、远端分支名对吗。五条过完，pre-receive hook declined基本就无处遁形了。
