简介在GitLab中pre-receive钩子是代码入库前的最后一道防线而这份资源正是用Go语言实现的轻量版提交消息检查钩子。它面向GitLab管理员、DevOps工程师或对服务端钩子机制感兴趣的开发者用于在git push时拦截不合规的提交维护提交历史的整洁度也适合需要自定义消息规则、分支限制或作者验证的团队环境。压缩包共4个文件、约3KB包含Go源码、README说明、许可证及Git忽略规则整体结构精炼便于阅读借鉴。源码演示了遍历推送引用、提取最新提交消息并执行关键词校验的完整流程例如以提交信息是否包含“fix”作为放行条件同时补充了部署到hooks目录、测试拦截效果的方法说明帮助快速验证效果。已有1991人学习该资源。通过这份示例可以清晰理解GitLab服务端钩子的触发时机与参数传递方式掌握用Go编写自定义检查逻辑的核心思路并进一步扩展多关键词匹配、作者身份校验、分支推送受限、日志记录等能力是兼具学习与二次开发价值的轻量参考。1. 一次 merge 把乱码提交推上主干之后我开始认真看 pre-receive 钩子GitLab 上真正拦住「坏提交」的最后一道闸门不是 MR 里的 CI也不是 code review而是服务端的 pre-receive 钩子。它跑在 Git 服务端、在你的git push指令到达 ref 更新之前能基于 commit message、文件变更、甚至提交者身份决定这一批推送是放行还是打回。最常见的用法就是「commit 消息检查」比如强制消息里带需求单号、禁止 WIP、禁止空消息、规范 Conventional Commits 格式。我这次要讲的就是在某个私有 GitLab 实例上用一个只依赖系统自带组件的 bash 脚本把「消息里必须有 [JIRA-xxx]」这种规则做成全局强制校验的全过程。适合刚接手 GitLab 维护、被乱提交折磨、又不想引入额外重量级服务的人你需要的只是 SSH 到 GitLab 服务器、知道钩子目录在哪、以及能用 bash 写 if。2. pre-receive 钩子到底跑在哪服务端钩子的执行时序与配置选型2.1 先分清两套 pre-receive仓库内 hooks 与全局 custom hooksGit 本身的钩子放在各个仓库的.git/hooks/目录下也就是裸仓库里的hooks/子目录。但 GitLab 托管项目的仓库目录在/var/opt/gitlab/git-data/repositories/namespace/project.git下直接往那里面丢脚本升级 GitLab 或做磁盘迁移时会被覆盖或丢失。GitLab 官方支持的是「custom hooks」机制把钩子脚本放进 GitLab 统一管理的目录GitLab 在每次推送事件到来时去调这些脚本。常见做法有两种全局 custom hooks 目录在gitlab.rb里配置gitlab_shell[custom_hooks_dir]这个目录下的脚本对所有项目生效项目级 custom hooks在某个项目的custom_hooks/子目录里放pre-receive脚本仅对该项目生效。这两个路径的使用场景完全不同。项目级适合试点和灰度改一个项目不影响其他人全局适合团队规范落地一次配置所有项目都被拦。我建议先走项目级规则稳定后再切全局。2.2 GitLab 配置路径与开启方式custom_hooks_dir vs gitlab-shell先确认你手上的 GitLab 版本。Omnibus 安装包在/etc/gitlab/gitlab.rb里配置源码安装则在config/gitlab.yml里。以 Omnibus 为例全局钩子目录一般设置成这样# /etc/gitlab/gitlab.rb gitlab_shell[custom_hooks_dir] /var/opt/gitlab/git-data/custom_hooks设置完之后要执行gitlab-ctl reconfigure让配置生效。这里有一个容易忽略的点custom_hooks_dir 配置好之后GitLab 会在这个目录下寻找pre-receive、post-receive、update三个脚本文件文件名必须完全一致不能带.sh后缀。如果你在本地调试时习惯命名成pre-receive.sh拷到服务器上就得改名否则 GitLab 压根不会执行它——脚本存在但没被执行这是最隐蔽的无效配置。项目级钩子则不需要改gitlab.rb只需要在项目仓库目录下这样操作# 在 GitLab 服务器上进入某个项目仓库 PROJECT_REPO/var/opt/gitlab/git-data/repositories/xxx/yyy.git mkdir -p $PROJECT_REPO/custom_hooks cp /path/to/pre-receive $PROJECT_REPO/custom_hooks/pre-receive chmod x $PROJECT_REPO/custom_hooks/pre-receive chown -R git:git $PROJECT_REPO/custom_hooks执行权限和属主这两个细节是坑中坑。脚本没加执行位GitLab 调用时直接报错或者静默失败属主不是 git 用户GitLab 进程可能因为权限不足读不到脚本。我每次部署完都会顺手ls -l看一眼确认权限位。2.3 执行时序与 stdin 协议oldrev、newrev、refname 逐个说清pre-receive 脚本是由 GitLab 的 gitlab-shell 进程调用的脚本通过标准输入 stdin 一次读到一行或多行每行由三个字段组成空格分隔oldrev newrev refname第一行示例0000000000000000000000000000000000000000 6a6c9f03f5d0f0d6f1a5f9a0e6cd8f3d9f25e3f7 refs/heads/masteroldrev是当前分支指向的旧 commit 哈希如果是从空分支推送则是一串全零newrev是推送完成后分支将要指向的新 commit 哈希refname是被更新的引用名称比如分支refs/heads/feature/xxx或标签refs/tags/v1.0.0。重要的一点一次 push 可能更新多个引用。比如你同时git push origin master:master dev:devstdin 里就会出现两行脚本必须逐个读取处理。而且 oldrev 和 newrev 之间是新旧两个提交点这两个点之间的全部 commit 都是这次推送引入的。检查 commit message就是遍历 oldrev..newrev 这个范围内的每个 commit。另外需要明确 pre-receive 与 update 钩子的分工pre-receive 在引用被更新前执行可以一次性看到本批次所有引用变化适合做统一的前置检查update 钩子则对每个引用单独执行一次参数里明确带上 refname、oldrev、newrev。commit message 检查用 pre-receive 更合适因为可以在脚本里自己控制遍历范围避免同一次推送多个分支时的重复执行。3. 提交消息检查脚本从 20 行原型到可维护版本3.1 最小可用的 bash 版本一个文件实现格式拦截先给一个门槛最低的原型脚本。它只做一件事读 stdin 里每一行拿到 oldrev 和 newrev然后用git rev-list遍历范围内的所有 commit逐个检查 commit message 是否以[需求号]开头。不满足就输出错误原因并返回退出码 1让 GitLab 拒绝这次推送。#!/bin/bash # pre-receive: 最小可用的 commit message 检查钩子 # GitLab 环境里 git 命令可用但需要确保在正确的仓库目录内执行 REPO_DIR$PWD export GIT_DIR$REPO_DIR # 从标准输入逐行读取 oldrev、newrev、refname while read oldrev newrev refname; do # 跳过 tag 引用只检查分支 case $refname in refs/tags/*) continue ;; esac # 处理新增分支/删除分支的情况oldrev 为全零则从新分支首个 commit 开始 if [ $oldrev 0000000000000000000000000000000000000000 ]; then range$newrev elif [ $newrev 0000000000000000000000000000000000000000 ]; then # 删除分支不需要检查 continue else range${oldrev}..${newrev} fi # 遍历范围内的每个 commit逐条检查 commit message for commit in $(git rev-list $range); do msg$(git log -1 --format%s $commit) if ! echo $msg | grep -qE ^\[(JIRA|TASK|BUG)-[0-9]\]; then echo pre-receive hook: commit $commit 的 message 不符合格式要求 echo 期望格式: [JIRA-1234] 简要描述 echo 实际内容: $msg exit 1 fi done done exit 0这段逻辑其实只有四步读 stdin、构造遍历范围、遍历 commit、判断格式。注意export GIT_DIR$REPO_DIR这行GitLab 的 custom hook 执行时工作目录通常是仓库本身但显式设置 GIT_DIR 更稳避免 git 子命令找不到 HEAD 或者报错。循环里的git rev-list每次执行都是一个独立进程提交一多性能就成问题。更优的写法是一次性把所有提交的 message 拿出来然后循环处理。我在原型版本里先用这种写法是因为它最容易排错——某个 commit 出问题马上就能看到哈希和 message。3.2 覆盖 push 多个 commit 的场景用 git rev-list 遍历上面那个版本能跑但有两个显眼的短板一是字符串拼接 commit 列表消息里带空格或特殊字符时容易出问题二是每次调用git log只取一个 commit推送 100 个 commit 就要启动 100 个 git 进程慢到不可接受。更稳的做法是先用git rev-list拿全量 commit 列表再用git log一次性把所有 message 读出来最后用关联数组或临时文件做配对。下面这个版本我在实际环境里已经跑了大半年#!/bin/bash # pre-receive: 批量检查 commit message 的稳定版本 # 读取 stdin 全部内容后续统一处理 input$(cat) # 遍历每一行引用更新 echo $input | while read oldrev newrev refname; do case $refname in refs/tags/*) continue ;; esac if [ $oldrev 0000000000000000000000000000000000000000 ]; then range$newrev elif [ $newrev 0000000000000000000000000000000000000000 ]; then continue else range${oldrev}..${newrev} fi # 用 rev-list 拿到 commit 列表存到变量里 commits$(git rev-list $range) # 对每个 commit 检查 message for commit in $commits; do subject$(git log -1 --format%s $commit) case $subject in [JIRA-*|[TASK-*) ;; *) # 对 merge commit 做特殊放行 is_merge$(git cat-file -p $commit | head -1) if [ $is_merge tree ]; then parents$(git cat-file -p $commit | grep ^parent | wc -l) if [ $parents -ge 2 ]; then continue fi fi echo ❌ 提交 $commit 未通过 message 检查 echo 期望前缀: [JIRA-数字] 或 [TASK-数字] echo 实际内容: $subject exit 1 ;; esac done done exit 0这个版本里 merge commit 的判断逻辑很关键。实际团队里总有人从 master 合并到 feature 分支时git 自动生成 merge commitmessage 往往不带需求号。如果你不进行特殊处理每次git merge master再推送都会被误杀开发者的体验会非常崩溃。判断方式是看提交对象里parent的数量两个及以上就直接放行。3.3 返回值、错误输出与退出码设计让前端同学一眼看懂拒绝原因钩子脚本的退出码决定了一切0 放行非 0 拒绝而脚本往 stdout/stderr 输出的文本会原样回显给 push 的客户端。这就引出一个落地准则错误信息必须足够直白让开发者看到就知道自己怎么改。我踩过的一个反面教材是早期的脚本只输出一行pre-receive hook declined推送的人看到这个一脸疑惑还得私聊管理员来问到底哪不合格。后来我把错误输出改成了三行结构第一行说明哪条 commit 有问题第二行说明期望格式第三行给出实际 message 内容。这样一份改动量很小的输出改进把团队的咨询量打掉了八成。代码实现就是在echo时做多行输出没有别的技巧。还有一点脚本内任何未预期错误都应该导致拒绝而不是静默放行。比如git rev-list执行失败说明仓库状态本身有问题此时宁可打断推送也不要让一批未经验证的 commit 溜进主干。所以我习惯在脚本开头加一个简单的环境自检if ! git rev-parse --git-dir /dev/null 21; then echo pre-receive hook: 无法定位 git 仓库已拒绝推送 exit 1 fi4. 部署到 GitLab两个落地方向与配置细节4.1 方向 A全局 custom_hooks_dir适合全团队推广全局钩子的好处是配置一次所有项目的推送都进入检查通道。前面已经给过设置项这里补完整操作序列。在 GitLab 服务器上依次执行以下命令mkdir -p /var/opt/gitlab/git-data/custom_hooks cat /var/opt/gitlab/git-data/custom_hooks/pre-receive EOF #!/bin/bash # 粘贴你最终的检查脚本 EOF chmod 755 /var/opt/gitlab/git-data/custom_hooks/pre-receive chown git:git /var/opt/gitlab/git-data/custom_hooks/pre-receive这里我刻意用了chmod 755而不是chmod x目的是让 owner 具备写权限其他用户只读降低脚本被意外改动风险。属主设置成git:git是因为 Omnibus 安装时 gitlab-shell 进程以 git 用户运行脚本需要被这个用户读取并执行。然后修改/etc/gitlab/gitlab.rbgitlab_shell[custom_hooks_dir] /var/opt/gitlab/git-data/custom_hooks最后执行gitlab-ctl reconfigurereconfigure 完成之后不必重启整个 GitLabgitlab-shell 会自行读取新的钩子目录。但如果你不确定配置是否生效可以用gitlab-ctl status看组件状态或者干脆找一个测试项目推一次不符合规范的消息用真实推送验证。4.2 方向 B项目级 custom_hooks适合灰度试点全局钩子一把梭的风险在于如果规则本身有 bug所有开发者立刻被阻塞。稳妥的做法是先在一个构建频率低、不阻塞主流程的仓库上试点跑两周没问题再推广到全局。项目级钩子的配置路径在 GitLab 的仓库目录里实际操作时建议用 Rails Runner 或文件查找来定位仓库。这里以/var/opt/gitlab/git-data/repositories下某个模拟项目 X 为例PROJECT_REPO/var/opt/gitlab/git-data/repositories/devops/simulation-project.git mkdir -p $PROJECT_REPO/custom_hooks install -m 755 /tmp/pre-receive $PROJECT_REPO/custom_hooks/pre-receive注意install命令比cp多做了三件事自动创建父目录没父目录时、设置权限位、保留属主。-m 755指定的权限和前面保持一致。做完这些之后不用跑 reconfigure项目级钩子实时生效。这和全局钩子的行为差异我放在踩坑章节里讲。4.3 应用后的快速验证推一次坏消息检查拦截效果验证是整个链路里最容易糊弄过去的地方我见过好几次「钩子部署完成但没人真正推过坏提交测试」等到出了问题才回头看配置。验证的完整流程应该是这样的先在一个本地测试仓库里故意做一条坏提交mkdir /tmp/hook-test cd /tmp/hook-test git init git remote add origin ssh://git你的gitlab域名/devops/simulation-project.git echo test a.txt git add a.txt git commit -m bad commit without ticket number git push origin master推送时如果钩子生效你会看到类似下面这样的输出remote: ❌ 提交 6a6c9f03 未通过 message 检查 remote: 期望前缀: [JIRA-数字] 或 [TASK-数字] remote: 实际内容: bad commit without ticket number To ssh://git你的gitlab域名/devops/simulation-project.git ! [remote rejected] master - master (pre-receive hook declined)重点看remote rejected字样只要出现说明钩子确实拦住了推送。然后再改一条合规的消息推送确认放行路径正常。两头都验证过钩子才算真正落地。部署过程中如果发现远程仓库地址里的项目路径不对可以在 GitLab 项目首页的「Clone」按钮处复制 SSH 地址不要手敲路径少一个排查面。5. 避坑pre-receive 钩子常见的 5 个翻车现场5.1 本地执行正常推送时却提示「远程钩子被拒绝」这个坑几乎每个人都会遇到。你本地测试脚本时是直接在 bash 里跑的甚至能手动往 stdin 里塞数据验证逻辑但推到远程就报错。原因有两类。一类是脚本里用了本地才有的命令比如grep -P的 Perl 正则在某些发行版上需要额外安装另一类是脚本里没有#!/bin/bash这一行或者行尾被文本编辑器改成了 CRLF。GitLab 的 gitlab-shell 调用钩子时依赖 shebang 来解释执行没有它就只能用系统默认 shell行为差异很大。解决方式所有钩子脚本统一以#!/bin/bash开头写完以后在服务器上跑file pre-receive确认不是CRLF行尾格式。如果在 Windows 下编辑过脚本用sed -i s/\r$// pre-receive清掉回车符。5.2 钩子只检查了最后一个 commit 的消息中间的全被跳过原型版本里我用for commit in $(git rev-list $range)遍历列表时有个隐藏问题如果脚本里有任何一行输出到了 stdout而这些输出恰好改变了 git 的缓冲区行为处理顺序就乱了。更常见的是新手把for循环放在了while read oldrev newrev refname的管道子 shell 外面导致变量只在管道后的子进程里更新循环体根本没执行到多个 commit。典型的错误结构echo $input | while read oldrev newrev refname; do # 处理 done # 在这里遍历 commits此时 oldrev/newrev 已经不可见解决方式把while改成for line in $(echo $input)或者把while包在{}里让整个循环在同一进程内运行。我最常用的是直接while ... done $input用 here-string 避免子 shellwhile read oldrev newrev refname; do echo $oldrev $newrev $refname done $input5.3 推送被拒绝后仓库锁一直被占用下一个 push 卡住这是 pre-receive 特有的一个坑脚本里如果执行了比较耗时的操作比如拉远程、调用外部 API、或者git gc会在推送过程中持有仓库的引用锁index.lock。一旦超过 GitLab 的某个超时时间推送进程被强制杀掉锁文件却残留下来。现象是下一个开发者推送时直接卡住服务器ps能看到 git 进程但无法正常结束。解决方式脚本里严禁调用写操作类的 git 命令。git log、git rev-list、git cat-file这些只读命令安全git gc、git repack、git fetch这类必须从钩子里删除。如果发现锁文件已经残留登录服务器到对应仓库目录找到*.lock文件删掉即可find /var/opt/gitlab/git-data/repositories -name *.lock -mmin 5 | xargs rm -f5.4 merge request 合并时钩子不生效或被绕过Matter 现象普通 push 会被拦住但点 GitLab 界面上的「Merge」按钮时提交就绕过检查合入分支了。原因在于 pre-receive 钩子只在「推送」这个动作时执行而 GitLab 执行 Merge 时直接在服务端做 ref 更新走的是内部 API 而不是 push 协议所以 pre-receive 不会触发。这不是 bug是设计如此。solution 是不要指望 pre-receive 独立兜底。GitLab 层面同时打开「推送规则」功能仓库设置里有 Push Rules把 commit message 正则要求配在服务端这样无论 push 还是 merge 都会被约束。或者接受它只拦截 push 的定位把主分支的保护规则打开只允许 Merge Request 合入再配合 CI 来检查。5.5 字符串匹配没扛住中文和特殊符号消息带引号时判断错乱嗯这个更精确。使用case $subject in [JIRA-*|[TASK-*)这种 glob 模式匹配核心逻辑没问题但中文字符和特殊符号在 locale 异常时会诱发模式匹配错误。我遇到过LC_ALLC环境下[[:space:]]这类 POSIX 字符类对中文空格无效导致消息里的全角空格把模式破开。解决方式是在脚本开头显式设置 localeexport LC_ALLen_US.UTF-8 export LANGen_US.UTF-8如果还不行就改成用 grep 精确匹配if ! echo $subject | grep -qE ^\[(JIRA|TASK)-[0-9]\]; then echo 检查未通过 exit 1 fi这个做法有一个副作用grep 参与判断后特殊字符的影响更可控因为正则能精确描述字符集。两个方案里我最终选择了 glob 优先grep 兜底的混合策略因为 grep 的-E在跨平台上差异同样存在没有绝对稳妥的唯一解。6. 进阶把钩子从「能用」变成「好用」的 4 个技巧6.1 先 fast-fail 再慢校验把 I/O 时间放最后推送大量 commit 时git rev-list全量遍历会拖慢整个 push 的反馈时间开发者会以为卡死了。优化方式是先把最廉价的前置检查做完再去做昂贵的全量遍历。比如先检查 commit 总数超过 500 个就直接拒绝并提示拆分为小批量推送再检查 refname 是否合法最后才开始逐条读 message。这样最耗时的 I/O 操作只会发生在前面几道关卡都通过的前提下。total_commits$(git rev-list $range | wc -l) if [ $total_commits -gt 500 ]; then echo 本次推送 commit 数量过多请分批推送 exit 1 fi6.2 用 report_file 输出多行错误推送端不再是一团乱码Git 在推送失败时会把远程输出整理成成块的错误消息默认情况下 stdout 和 stderr 混在一起客户端看到的排版很乱。GitLab 的 custom hook 支持额外约定如果钩子脚本往一个临时文件里写入结构化错误错误展示会更清晰。这个技巧来自 git 内置文档实际操作是在脚本里定义一个固定路径的临时文件把错误细节以error: ....格式写进去最后主进程退出非 0 时GitLab 客户端会优先展示文件内容。REPORT_FILE$(mktemp) echo error: commit message 需要包含需求单号例如 [JIRA-1234] $REPORT_FILE echo error: 违规 commit: $subject $REPORT_FILE # 退出前输出报告文件再删除 cat $REPORT_FILE 2 rm -f $REPORT_FILE注意这只是让信息更可读不会改变拦截行为。真正决定拒绝的是退出码。6.3 把规则抽成配置文件改规则不用动脚本当团队规范迭代变快时例如从只允许 JIRA 单号变成也允许缺陷单号每次改脚本都存在重新部署的风险。我在项目里会把规则写到单独的配置文件里脚本启动时读取它。CONFIG_FILE/var/opt/gitlab/git-data/custom_hooks/rules.conf if [ -f $CONFIG_FILE ]; then source $CONFIG_FILE else # 默认规则 PREFIX_PATTERN^\[(JIRA|TASK)-[0-9]\] fi if ! echo $subject | grep -qE $PREFIX_PATTERN; then echo commit message 必须以 $PREFIX_PATTERN 开头 exit 1 fisource方式在 shell 里就是读取变量定义传递规则时注意配置文件不能有危险命令否则等于 RCE 后门。这个只适合可信团队内部使用。6.4 灰度策略先 warn 后 block给团队一个适应期如果你直接启用 block第二天早上开发者的第一个 push 就会红屏免不了有人在群里发牢骚。稳妥做法是钩子上线后先跑两周「警告不拦截」模式违规的 commit 照常放行但输出 warning 提示。MODEwarn # 灰度期改成 block 进入强制模式 if ! echo $subject | grep -qE $PREFIX_PATTERN; then if [ $MODE warn ]; then echo warning: commit message 不符合规范后续将禁止推送 echo warning: $subject else echo error: commit message 不符合规范已拒绝推送 exit 1 fi fi灰度期观察两个指标团队是否开始改习惯、误拦的比例高不高。两周后把MODE改成block钩子就正式进入强制阶段此时集体的接受度会高很多。这套钩子我在内部推行下来最深的体会是强制规则想落地先让开发者看到规则、再让规则越来越严比一次性下狠手要平顺得多。希望帮到你。本文还有配套的精品资源点击获取
