5分钟上手Gitea钩子脚本：让Git操作自动触发工作流-优快云博客

5分钟上手Gitea钩子脚本：让Git操作自动触发工作流

【免费下载链接】gitea Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD 项目地址: https://gitcode.com/GitHub_Trending/gi/gitea

你还在手动处理代码提交后的部署通知、数据备份？Gitea钩子脚本（Hook Script）能帮你自动完成这些重复工作。本文将带你快速掌握钩子类型、配置步骤和实战案例，让Git操作成为自动化工作流的起点。

读完本文你将学到：

识别4种关键钩子类型及其触发时机
3步完成自定义钩子配置
部署通知/自动测试等5个实用场景模板
基于日志的钩子调试技巧

钩子脚本是什么？

钩子脚本是嵌入在Git操作流程中的自定义程序，能在特定事件（如代码提交、分支创建）发生时自动执行。Gitea通过cmd/hook.go实现了对Git原生钩子的增强管理，支持更复杂的业务逻辑集成。

工作原理

mermaid

核心钩子类型

钩子名称	触发时机	典型用途
pre-receive	接收推送前	代码合规检查、权限验证
update	分支更新时	保护分支规则校验
post-receive	推送完成后	部署通知、CI触发
proc-receive	Git 2.29+ 协议扩展	复杂引用更新处理

钩子执行逻辑定义在cmd/hook.go#L31-L91，其中proc-receive是Git 2.29新增的高级特性

快速配置指南

1. 启用钩子功能

修改配置文件custom/conf/app.example.ini，确保以下设置：

[security]
; 允许自定义Git钩子（生产环境建议仅对可信用户开放）
DISABLE_GIT_HOOKS = false

2. 创建钩子脚本

在仓库的hooks目录创建对应钩子文件（需设置可执行权限）：

# 以post-receive钩子为例
cd /path/to/repo.git/hooks
touch post-receive
chmod +x post-receive

3. 编写脚本逻辑

编辑钩子文件添加自定义逻辑，例如发送邮件通知：

#!/bin/bash
while read oldrev newrev refname; do
  # 提取分支名
  branch=$(git rev-parse --symbolic --abbrev-ref $refname)
  
  # 发送通知（实际使用时替换为你的SMTP配置）
  echo "代码已推送到$branch分支: $newrev" | \
  mail -s "Gitea推送通知" team@example.com
done

实用场景模板

1. 部署通知到企业微信

#!/bin/bash
# 企业微信机器人Webhook地址
WEBHOOK_URL="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=XXX"

while read oldrev newrev refname; do
  branch=$(git rev-parse --symbolic --abbrev-ref $refname)
  # 获取提交者信息
  committer=$(git log -1 --pretty=format:"%an <%ae>" $newrev)
  
  # 构建消息体
  payload='{
    "msgtype": "markdown",
    "markdown": {
      "content": "**代码推送通知**\n> 分支: '$branch'\n> 提交者: '$committer'\n> 提交信息: '$(git log -1 --pretty=format:%s $newrev)'"
    }
  }'
  
  # 发送请求
  curl -s -H "Content-Type: application/json" -d "$payload" $WEBHOOK_URL
done

2. 自动触发Jenkins构建

#!/bin/bash
JENKINS_URL="http://jenkins.example.com/job/myproject/build"
JENKINS_TOKEN="my-token"

while read oldrev newrev refname; do
  branch=$(git rev-parse --symbolic --abbrev-ref $refname)
  
  # 仅构建main分支
  if [ "$branch" = "main" ]; then
    curl -X POST "$JENKINS_URL?token=$JENKINS_TOKEN&branchName=$branch"
  fi
done

3. 提交信息合规检查（pre-receive）

#!/bin/bash
# 检查提交信息是否包含JIRA工单编号

while read oldrev newrev refname; do
  # 遍历所有新增提交
  for commit in $(git rev-list $oldrev..$newrev); do
    msg=$(git log -1 --pretty=format:%s $commit)
    # 检查是否匹配JIRA格式 (PROJ-XXX: 描述)
    if ! echo "$msg" | grep -qE '^[A-Z]+-[0-9]+: .+'; then
      echo "ERROR: 提交信息不符合规范: $msg"
      echo "正确格式示例: PROJ-123: 修复登录bug"
      exit 1  # 阻止推送
    fi
  done
done

调试与故障排除

日志查看

钩子执行日志默认记录在Gitea日志文件中，可通过以下命令筛选：

grep "hook" /path/to/gitea/log/gitea.log

常见问题解决

钩子不执行
- 检查文件权限是否可执行
- 确认custom/conf/app.example.ini中DISABLE_GIT_HOOKS是否设为false
中文乱码
- 在脚本开头添加export LANG=en_US.UTF-8
- 确保Gitea服务器环境变量设置正确
执行超时
- 对于长时间运行的任务，考虑使用后台执行：
```
# 在钩子脚本中
nohup /path/to/long-running-task &
```

高级特性

钩子链管理

通过contrib/init目录下的系统服务模板，可以实现钩子脚本的集中化管理。例如systemd服务配置：

[Unit]
Description=Gitea Hook Manager
After=gitea.service

[Service]
User=git
ExecStart=/usr/local/bin/gitea-hook-manager
Restart=always

[Install]
WantedBy=multi-user.target

基于环境变量的动态配置

Gitea在执行钩子时会注入丰富的环境变量，可在脚本中直接使用：

#!/bin/bash
# 打印所有Gitea注入的环境变量
env | grep -E '^GITEA_|^REPO_' > /tmp/hook-env.log

# 使用示例: 获取仓库所有者
echo "仓库所有者: $REPO_OWNER"

总结与最佳实践

安全性：生产环境建议通过custom/conf/app.example.ini#L483限制钩子权限，避免恶意代码执行
可维护性：复杂逻辑建议拆分为独立脚本，钩子中仅保留调用入口
版本控制：将钩子脚本纳入Git管理，通过工具自动同步到Gitea服务器
监控：对关键钩子添加执行状态监控，推荐使用Prometheus+Grafana组合

通过钩子脚本，Gitea能与你的DevOps工具链深度集成，实现从代码提交到产品发布的全流程自动化。下一篇我们将探讨如何结合Gitea Actions实现更复杂的工作流编排。

收藏本文，关注项目更新获取更多自动化技巧！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考