简介：一份用Go语言实现的GitLab pre-receive钩子示例，面向需要为团队Git仓库增加提交规范校验的研发工程师与DevOps管理员，主要用于解决推送阶段无法拦截不符合规范commit消息的问题。钩子在服务器端读取待推送的引用和最新提交，若提交消息缺少指定关键词则以非零状态退出，从而拒绝推送。压缩包内仅4个文件，涵盖main.go核心源码、README说明、开源许可和.gitignore配置，整体约3KB，结构十分精简，便于逐一阅读和二次修改。目前已有1982人学习使用。通过这份材料，读者能够理解pre-receive钩子的工作流程，掌握使用Go调用git命令读取提交信息、判断并输出错误的方法；同时了解到钩子的部署位置、执行权限和退出码语义，并可根据项目需要扩展为检查作者、限制分支、记录日志等功能。适合具备Go基础、希望为GitLab仓库快速落地服务端校验策略的开发者参考，也可作为后续构建团队提交规范的起点。 做GitLab管理员这几年，我见过最糟心的事不是服务器宕机，而是翻提交记录的时候看到满屏的“fix bug”“update”“aaa”。版本好不容易发完，想追溯某个功能对应的提交，只能靠猜。后来我在服务端挂了一个pre-receive钩子，强制校验commit message，才把这个问题解决。这篇文章就从一个实际用过的gitlab commit消息检查钩子讲起，聊聊它的原理、部署过程和那些文档里不写的坑。适合GitLab管理员、研发负责人，以及所有不想再追着人改提交信息的同学。
1. 项目背景：为什么需要一个commit消息检查钩子
1.1 提交信息混乱的痛点
先看几个真实场景。团队十几个人，每人都有自己的提交习惯，有人用中文，有人用英文，有人干脆不写。一旦需要做版本回溯，比如线上出了bug，要定位“登录模块最近改了什么”，常规操作是翻git log，但你在log里看到的可能是commit test、修改代码、111这类完全没有信息的记录。这时候你唯一能做的就是挨个点开commit，看diff，效率非常低。
更麻烦的是，不规范的提交信息会影响自动化流程。比如你想用工具根据commit生成change log，或者用semantic-release做语义化版本发布，前提是commit message必须符合Conventional Commits约定。如果提交信息乱七八糟，脚本根本没法解析，整条自动化链路都会被卡住。
我经历的另一个坑是git账号和GitLab账号不一致。有人用个人邮箱提交代码，服务端显示的作者信息对不上，后续做代码量统计、权限追溯时全乱套。虽然这个问题不完全靠pre-receive解决，但钩子里可以一并校验作者邮箱，至少让数据可信。
1.2 为什么选pre-receive而不是其他方案
解决提交规范，方案其实不少，但我最终选了pre-receive。先说为什么不选其他方案。
第一个是客户端钩子，也就是每个开发者本地.git/hooks/pre-commit。这个方案实现起来很容易，但完全依赖开发者自觉。换台电脑、换个IDE、或者有人用命令行--no-verify跳过，钩子就成了摆设。我见过太多团队写了客户端脚本，最后形同虚设。
第二个是CI脚本检查。当代码推送到GitLab后，由CI任务校验提交信息。问题在于代码已经进到远端仓库，如果检查不通过，研发需要重新修改commit、强制推送，操作成本很高，而且一旦有人合并了MR，历史就被污染了。CI阶段能发现，但止损太晚。
第三个是GitLab企业版的push rules。这个功能正经好用，但社区版没有，对很多团队来说要额外掏钱，不划算。
最后就是pre-receive服务端钩子。它是Git原生的机制，在git push到达服务端时、写入仓库之前执行。只要钩子返回非零状态，整个push就被拒绝，提交根本进不了仓库。这种强制校验绕不过去，对所有人一视同仁。而且社区版就能用，不用额外付费。综合下来，pre-receive是性价比最高、最符合“强制”需求的选择。
2. 核心原理与钩子设计
2.1 pre-receive钩子如何工作
很多人一听到“GitLab钩子”就以为是什么特殊机制，其实底层就是Git原生的server-side hook。Git在每次接收push时，会在仓库目录下寻找pre-receive文件，如果存在且可执行，就会运行它。
钩子启动后，会从标准输入读取一行数据，格式是：
<旧ref值> <新ref值> <ref名称>例如：
0000000000000000000000000000000000000000 9dae6c42f1a0e0d5d5c6e0a58c27e9f1a8b51c3d refs/heads/main这行的意思是：有一个push想把refs/heads/main从全零（也就是不存在）更新到9dae6c4。如果是更新已有分支，旧ref值就是目标分支当前指向的commit；如果是删除分支，新ref值就是全零。
所以要检查这次push引入了哪些新提交，方法很简单：用git rev-list对比新旧ref之间相差的commit，然后逐一读取它们的message。对于新分支创建，旧ref是全零，需要列出新分支上所有可达提交；对于更新，就是git rev-list $oldrev..$newrev。
理解了底层机制，脚本逻辑就清晰了。一个pre-receive钩子本质上就是一个守门员，站在仓库门口，把不符合规则的提交挡在门外。
2.2 消息检查规则与设计思路
检查规则怎么定，是这项目的核心。我参考了Conventional Commits规范，结合团队实际，定了几条：
- message必须非空，且有实际内容，不能少于一定长度
- 必须以
type:开头，type限定在feat|fix|docs|style|refactor|perf|test|chore - 允许带scope，格式
type(scope): description - 对于merge commit，放宽要求，不强制检查，因为很多MR合并产生的提交信息是自动生成的，不应该卡
举个例子，一条合法的提交信息是：
feat(user): 增加用户登录页面或者：
fix(cart): 修复结算页金额计算错误不合法的提交信息包括：
updateaaa哈哈哈哈选择一个正则来匹配规则：
REGEX='^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-zA-Z0-9_-]+\))?: .{10,}$'简单拆解下：
^开头(feat|fix|...):type:前缀(\(...\))?: 可选的scope部分:: 冒号加空格，这是硬性格式，很多人会漏掉冒号后面的空格.{10,}: description部分至少10个字符
这个正则看着简单，但在实际使用中足够对付90%的场景。如果团队有更严格的内部编号要求，也可以改成必须包含issue编号，比如正则里加#[0-9]+。
2.3 脚本结构拆解
完整脚本我后面会放。这里先说下结构设计上的几个关键点。
处理标准输入。钩子可能收到多行数据，因为一个push可以同时更新多个分支。要用while read循环逐行处理。
判断删除分支。如果新ref全零，说明是删除操作，不需要检查，直接跳过。
判断新分支创建。如果旧ref全零，说明是新建分支，此时要用git rev-list "$newrev" --not --all找出这个分支独有的提交。如果直接用$oldrev..$newrev，因为oldrev是全零，命令结果不会正确。
跳过merge commit。通过git cat-file -p "$commit" | grep -c '^parent '统计父提交数量，如果大于1就跳过。这个逻辑实际测试很好用。需要说明的是，如果团队强制要求每个合并commit也走规范，可以去掉这个跳过逻辑。
错误提示要清晰。当检查不通过，钩子向标准错误输出提示，终端上的开发者会直接看到。我建议明确给出失败原因、规范要求和一个示例，避免开发者还要去翻文档。
脚本开头的set -uo pipefail是重点。set -e不建议用，因为一旦某个命令非零就退出，容易在循环里误判；-u防止变量未定义，pipefail能捕获管道中前一命令的失败。这些细节决定了脚本在压力下是否稳定。
3. 完整实操：在GitLab上部署pre-receive钩子
3.1 环境准备与目录结构
不同安装方式的GitLab，仓库路径不同。我以最常用的Omnibus包安装为例，项目仓库通常在：
/var/opt/gitlab/git-data/repositories/@hashed/...@hashed是GitLab 10以上版本默认的存储格式，真实路径是一长串哈希目录，不方便直接找。最简单的办法是在GitLab页面上找到项目地址，然后到服务器上搜：
find /var/opt/gitlab/git-data/repositories -name "*.git" -type d | grep 项目名找到项目仓库目录后，进入目录，检查有没有custom_hooks文件夹：
cd /var/opt/gitlab/git-data/repositories/<项目仓库> ls -la如果没有就创建：
mkdir custom_hooks注意：目录名是custom_hooks，不是hooks，也不要在仓库目录下乱放。GitLab的server hook机制就是固定找这个目录。
3.2 编写检查脚本
我提供一份完整的pre-receive脚本，可以直接复制到custom_hooks/pre-receive。为了可读性，我加了注释：
#!/usr/bin/env bash # GitLab pre-receive hook # 功能：检查push中的commit message是否符合规范 set -uo pipefail # 提交规范正则 # 格式: type(scope): description # type: feat|fix|docs|style|refactor|perf|test|chore REGEX='^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-zA-Z0-9_-]+\))?: .{10,}$' ZERO="0000000000000000000000000000000000000000" while read oldrev newrev refname; do # 删除分支/删除ref，跳过 if [ "$newrev" = "$ZERO" ]; then continue fi # 获取需要检查的commit列表 if [ "$oldrev" = "$ZERO" ]; then # 新分支创建，找出所有新分支独有的提交 commits=$(git rev-list "$newrev" --not --all 2>/dev/null) else # 更新已有分支，找出新增加的提交 commits=$(git rev-list "$oldrev".."$newrev" 2>/dev/null) fi for commit in $commits; do # 跳过merge commit parent_count=$(git cat-file -p "$commit" | grep -c '^parent ') if [ "$parent_count" -gt 1 ]; then continue fi msg=$(git log -1 --pretty=%B "$commit") # 检查message是否匹配 if ! echo "$msg" | grep -Eq "$REGEX"; then echo "" echo "ERROR: commit $commit 的message不符合规范" >&2 echo "实际message: $msg" >&2 echo "要求格式: <type>(<scope>): <description>" >&2 echo "示例: feat(user): 增加用户登录页面" >&2 echo "type范围: feat|fix|docs|style|refactor|perf|test|chore" >&2 echo "" exit 1 fi done done exit 0这里有几点要展开说。
一是git rev-list "$newrev" --not --all在新分支创建时会有个副作用：如果仓库里其他分支已经包含这个新分支的部分提交，那部分会被排除，只检查真正“新”的提交，这是正确的。如果开发者在本地已经merge过目标分支再push，--not --all会把目标分支已有的提交过滤掉，不会重复检查。
二是grep -Eq的正则匹配。这里用echo "$msg" | grep -Eq来检查，注意$msg如果包含多行，echo会输出多行，但是grep逐行匹配，只要有一行匹配就通过。对于多行commit message（比如有body），只要subject行符合规范就放行，这符合常见习惯。不过这个写法可能会有一个问题：如果description部分换行，.{10,}不会匹配换行符，导致多行commit message的subject如果很短，可能不通过。实际测试中，大多数commit message的subject都是单行，所以我没加head -1。如果你希望严格只检查第一行，可以改成：
msg=$(git log -1 --pretty=%B "$commit" | head -1)三是性能。git rev-list会遍历提交，如果一次push包含上千个commit，循环跑下来会有点慢。我实际项目中一次push最多也就几十个commit，体感没有延迟。如果仓库特别大，可以考虑用git log --format=...的批量方式，但脚本复杂度会上升，我建议先保持简单。
脚本写完后别忘了给可执行权限：
chmod +x custom_hooks/pre-receive还要确保脚本属主和权限对git用户可读可执行。通常custom_hooks目录和文件都应该是git:git属主，否则GitLab跑钩子时可能没权限。
3.3 授权、测试与上线
部署到GitLab后，强烈建议先在测试项目上验证，不要直接上生产。测试步骤是：
先准备一个不合规的push。在本地修改代码，提交一个message为“update”的commit，尝试推送：
git commit -m "update" git push origin test-branch正常情况下，终端会输出钩子的错误提示，并拒绝push。如果出现类似“remote: ERROR: commit ... 不符合规范”的信息，说明钩子生效了。再提交一个合规的：
git commit -m "fix(user): 修复登录按钮无法点击的问题" git push origin test-branch这次应该能推上去。
还有个小技巧：不依赖GitLab，直接在服务器上手动模拟钩子输入，快速测试脚本语法是否正常。在项目仓库目录下执行：
cd /var/opt/gitlab/git-data/repositories/<项目仓库> su - git -s /bin/bash -c 'echo "oldrev newrev refs/heads/main" | ./custom_hooks/pre-receive'这样能验证脚本的执行权限和基础逻辑，但要注意oldrev和newrev得填真实的commit哈希，不然git rev-list会报错。
上线前还要考虑一件事：让团队提前知道规则。我经历过最尴尬的场景，是钩子上线后一位同事的push被拒，他在群裡喊“为什么推不上去”。后来我专门写了一份提交规范说明，更新到项目README里，再遇到被拒的人直接把说明丢给他。
4. 常见问题与排查记录
4.1 钩子不生效
如果部署完钩子后，不合规的提交依然能推上去，优先从下面几个方向查。
检查路径。custom_hooks目录一定在项目仓库目录下，而不是随便建在别的地方。GitLab的项目仓库路径通过页面“项目设置-仓库”能看到。
检查文件名，必须是pre-receive，没有后缀，大小写敏感。pre_receive或者Pre-receive都不行。
检查执行权限。如果忘了chmod +x，GitLab可能不会运行它。可以用ls -l确认权限。
检查文件编码和shebang。脚本第一行必须是#!/usr/bin/env bash或者#!/bin/bash，如果文件带了Windows换行符，第一行会变成#!/usr/bin/env bash\r，导致“No such file or directory”这类诡异错误。用sed -i 's/\r$//' pre-receive清一下。
还有一个我踩过的坑：脚本里用exit 255，结果某些GitLab版本会把255当成SSH错误而不是hook拒绝，推送端报错非常迷惑。后来统一改成exit 1，问题消失。所以代码块里我写的都是exit 1。
4.2 误伤与白名单
钩子上线后最头疼的是误伤。比如有人提交了一个比较长的英文消息，但开头没有type前缀，被拒了；或者有人提交“feat: 修复接口超时”，description部分不够10个字符，也被拒了。这些情况需要权衡。
我的建议是，一开始不要把规则定得太死。比如先只要求以feat|fix|docs|style|refactor|perf|test|chore中任意一个开头，不检查长度和scope，跑两周看大家接受程度，再逐步收紧。
另外，有时候特定分支需要豁免。比如hotfix分支，研发急着修线上问题，可能提交信息非常简短。我提供了一个白名单处理：通过refname判断分支名，允许hotfix/前缀的分支跳过检查。只改一行：
if [[ "$refname" == refs/heads/hotfix/* ]]; then continue fi同理，如果你想允许特定用户绕过检查，可以读取GL_USERNAME环境变量。GitLab在运行hook时会注入这个变量，值是当前push的用户。比如允许admin跳过：
if [ "$GL_USERNAME" = "admin" ]; then continue fi但我不建议长期开放白名单，它会让规则失去意义。顶多用于紧急故障时的临时处理。
4.3 与CI/CD流程的衔接
pre-receive钩子和CI/CD是两个不同阶段的检查。pre-receive在push时拦截，CI在push之后或MR时运行。如果只靠CI，坏提交已经进了仓库，要改历史很麻烦；如果只靠pre-receive，只能检查commit message，没法验证代码质量。所以两者是互补的。
我的经验是：提交格式类、作者类、敏感信息类检查放pre-receive，保证“脏数据”进不来；代码规范、测试、构建类检查放CI，保证代码质量过关。这样各司其职，效率最高。
也有人会问，pre-receive能不能顺便扫描代码里有没有密码、密钥之类的高危信息？当然可以，只要在脚本里加上对diff内容的grep即可。不过要注意，pre-receive的定位是“轻量检查”，如果做得太重，push耗时上升，影响开发体验。真正的大规模扫描推荐放到CI里做定时任务。
5. 实操中的额外心得
最后再分享几个实际操作中总结的点。
第一，钩子脚本尽量保持简单。别在脚本里安装额外依赖，GitLab自带的环境里bash、grep、sed、git这些常用命令都有，但你没有保证有python或ruby。如果你开始写几百行的钩子，后续维护成本会很高。能用bash实现的功能就别引脚本语言。
第二，错误提示要有人情味。被拒的开发者本来就有点烦，如果你的提示只有“Commit message is invalid”，他可能还要去查规范。我在脚本里把格式、示例、type范围全部输出，他一眼就知道怎么改。实测反馈，这点很有效。
第三，部署钩子前先给仓库打个快照。虽然pre-receive本身不改任何数据，但如果脚本逻辑有误，可能会出现push被莫名拒绝的情况，在团队里影响很不好。所以我的建议是先在一个测试项目上跑一周，确认稳定后再推广到核心仓库。
第四，GitLab升级之后记得检查钩子是否还在。我遇到过几次升级后custom_hooks路径或者权限出现变化的情况，虽然GitLab官方承诺会保留，但谨慎一点总没错。每次升级完，我会跑一次“不合规push被拒”的验证。
这套pre-receive钩子我自己用了很长时间，最大的体会是：服务端校验确实能从底层改善提交卫生，但规则一定要根据团队实际节奏来定，一口吃不成胖子。先让大多数人能顺利提交，再慢慢提升规范度，才能避免抵触情绪。希望这篇文章里的脚本和踩坑经验能帮你少走一些弯路。
本文还有配套的精品资源，点击获取
` 抵御 Timing Attack)