GitLab 提交权限校验脚本

.git/hooks 目录详解与配置指南

一、什么是 .git/hooks？

.git/hooks 是 Git 仓库中一个隐藏目录 ，用于存放 钩子脚本（Hook Scripts） 。这些脚本会在 Git 执行特定操作（如提交、推送、合并）的前/后自动触发，允许开发者自定义逻辑（如代码校验、权限验证、自动化流程）。

二、钩子分类（按作用场景）

类型	触发时机	常见钩子名称	是否推送到远程仓库	权限要求
客户端钩子	用户本地操作（提交、推送、合并等）	pre-commit、commit-msg、pre-push	否（仅本地生效）	普通开发者权限
服务端钩子	远程仓库接收代码时（如 GitLab 服务器）	pre-receive、update、post-receive	否（需手动部署到服务端）	服务端管理员权限

三、客户端钩子：本地仓库配置（以 pre-commit 为例）

1. 目录位置

• 路径 ：<本地仓库>/.git/hooks/（注意 ：.git 是隐藏目录，需显示隐藏文件）。
• 默认文件 ：Git 会提供 .sample 后缀的钩子模板（如 pre-commit.sample），可复制重命名后编辑。

2. 配置步骤

步骤 1：创建/编辑钩子脚本

cd your-repo/.git/hooks/
# 复制模板（可选）
cp pre-commit.sample pre-commit
# 或直接创建新文件
nano pre-commit

步骤 2：编写脚本（示例：检查代码格式）

#!/bin/sh
# pre-commit：提交前检查代码格式
echo "正在检查代码格式..."

# 执行代码检查命令（如 ESLint、Pylint）
if [ "$(git diff --cached --name-only | grep -e '\.js$\|\+.ts$')" ]; then
  npx eslint . --ext .js,.ts --fix
  if [ $? -ne 0 ]; then
    echo "Error: 代码格式检查失败，提交终止！"
    exit 1
  fi
fi

exit 0

步骤 3：赋予执行权限

chmod +x pre-commit

步骤 4：验证效果

git commit -m "test"  # 触发 pre-commit 钩子

四、服务端钩子：以 GitLab 为例（pre-receive 钩子）

服务端钩子在 Git 服务器接收代码时触发 ，需在服务器端仓库的 .git/hooks/ 目录配置（需管理员权限）。

1. 适用场景

• 权限校验（如用户提交需审批）
• 分支保护（如禁止直接推送主分支）
• 合规检查（如 commit 信息必须符合规范）

2. 配置步骤（以 GitLab 服务器为例）

步骤 1：登录服务器并定位仓库

# 服务器端仓库路径（示例）
cd /var/opt/gitlab/git-data/repositories/<group-name>/<project-name>.git/hooks/

步骤 2：创建 pre-receive 脚本（示例：调用 API 校验权限）

{insert\_element\_0\_}

步骤 3：赋予执行权限

chmod +x pre-receive

步骤 4：验证效果

# 从客户端推送代码，触发服务端钩子
git push origin main

五、常用钩子列表

钩子名称	触发时机	典型用途
pre-commit	git commit 命令执行前	代码格式检查、单元测试、敏感信息扫描
commit-msg	提交信息写入前（可修改提交信息）	验证 commit message 格式（如 Jira 单号）
pre-push	git push 命令执行前	跨仓库检查、依赖项校验、集成测试
pre-receive	服务端接收推送前（仅服务端钩子）	权限校验、分支保护、合规性检查
post-receive	服务端接收推送后（仅服务端钩子）	触发 CI/CD 流程、通知系统、更新镜像仓库

六、最佳实践

1. 避免硬编码路径：使用相对路径或环境变量，确保钩子在不同环境下正常运行。
2. 添加错误处理 ：用 try-catch 或 if 判断防止钩子意外终止操作。
3. 客户端钩子不推送到远程 ：.git/hooks/ 目录不会被 Git 跟踪，需手动在每个客户端配置（或通过项目模板分发）。
4. 服务端钩子高可用：在分布式系统中，需确保钩子脚本部署在所有 Git 节点（如 GitLab 的 Gitaly 集群）。
5. 使用工具简化管理 ：
   • Husky（客户端）：简化 Git 钩子管理，支持 JavaScript/TypeScript（适用于 Node.js 项目）。
   • GitLab CI/CD ：结合 pre-receive 钩子实现更复杂的流水线校验。

七、常见问题

1. 钩子不生效？

   • 检查脚本是否有执行权限（chmod +x hook-name）。
   • 确认钩子名称正确（如 pre-commit 而非 pre-commit.sh）。
   • 客户端钩子仅在本地生效，服务端钩子需部署到服务器。

2. 如何调试钩子？

   • 在脚本中添加日志（如 echo "Debug: $var" >> hook.log）。
   • 使用 git commit --no-verify 跳过客户端钩子（临时禁用）。

3. GitLab 替代方案：Webhook

   • 若无法直接修改服务端钩子，可通过 GitLab 的 Webhook（设置 → 集成 → Webhooks）实现类似功能，在推送后触发外部服务（如校验接口）。

通过合理配置 .git/hooks，可以将代码质量检查、权限控制、自动化流程等逻辑无缝集成到 Git 工作流中，提升团队协作效率和代码合规性。