git-hookgit-hook是一个搭建在远端服务器上的git钩子服务,它有着远大的理想,但目前实现较为简单。现在绝大多数git仓库管理平台都支持设置一个回调URL,包括github、oschina、Coding等。当开发者在本地push代码到远程时,就会向该URL发起请求,接收该请求的服务器可以在本地运行一个配置好的命令。该工具就是用来管理这些命令的。 特性: - 单服务器,需要在运行命令的服务器上搭建本服务。
- 支持多平台,包括github、oschina、coding等。
- YAML配置文件,语法好用简洁。
- 命令的配置支持user、group、cwd、stdout和stedrr的重定向。
- 友好的错误提示以及日志。
快速部署前置条件: - Linux系统
- 已安装node和yarn,node版本需要在v6及以上
部署步骤: yarn - 参考配置文件规则部分
- 启动:
yarn start
重启: 在任何配置文件修改的时候,都需要重启服务以重载配置。
关于sudo服务的启动一定要加入sudo来以root身份运行。因为工具支持切换用户和用户组执行命令,只有root用户才能无缝支持用户和用户组的切换,其他身份切换都需要提供密码。当然,也可以不以root身份运行,但在配置文件内的user和group字段必须设置为当前用户和组,否则工具就会报错。 命令参数服务器启动时支持一些参数: 配置文件规则hook配置存放在config目录下,配置文件的结构参考examples/simple-hook.yml和examples/full-hook.yml文件。配置文件需要以.yml结尾,其他的任何后缀都会略过。 待配置的URL与配置文件的路径是一一对应的关系,例如相对于config目录的配置文件a.yml,它的URL子路径必须是/a,相对于config目录的配置文件a/b.yml,他的URL子路径必须是/a/b.yml. 配置文件的字段解释如下: token : 一个密钥,用于验证请求的有效性。当设置此字段时,任何token不匹配的请求都会被拒绝;当没有设置此字段时,不作验证,接受任何请求。强烈建议设置此字段。branch : 一个通配符形式的分支字段过滤器。任何不匹配的请求都会被当前配置拒绝,但一个配置文件内有多个配置,后续的配置仍然有可能接受此请求。默认值为* .event :一个通配符形式的事件字段过滤器,事件包括push、merge_request等。任何不匹配的请求都会被当前配置拒绝,但一个配置文件内有多个配置,后续的配置仍然有可能接受此请求。默认值为* .executor :配置执行器,具体参见命令与环境一节。对于一般用户来说,该字段填spawn就够了。command :执行的命令。cwd :命令执行环境的当前目录。user :命令执行的用户。group :命令执行的用户组。stdout :stdout重定向的文件路径。stderr :stderr重定向的文件路径。
基本上所有字段都是必填的,最好都写上去。 特殊的配置文件default.yml和特殊的配置键default根目录的default.yml内配置的内容会作为其他所有配置的默认值,参考examples/default.yml. 配置文件中键default对应的配置作为该文件中其他配置的默认值,参考examples/full-hook.yml. 综上,字段的覆盖规则为:特殊键、default键、default.yml. Hook的URL规则一个完整的URL格式为: http://{domain}:{port}/{path}?normalizer={normalizer} 该URL每个部分的解释为: domain : 能够访问到服务器的域名。port : 服务器启动的端口,该端口可以在启动时通过参数指定,默认为3000.path : path与配置文件的位置是一一对应的。normalizer : normalizer指定了规范化的方法,它一般是平台的名字,如github、oschina、coding等。目前只支持Coding,后续逐步加入其他的支持。也可以自己编写normalizer插件。
例如,你在coding.net平台上设置hook,并且配置文件在config/a/b.yml下,则路径地址一定得配置为 http://your-domain:port/a/b?normalizer=coding 命令与环境Linux的命令与执行环境有很大的关系,一时间很难彻底理清。Node提供了一个调用外部命令的方法child_process.spawn ,但这个方式在执行某些命令时会产生一些说不清楚的问题。为了解决这一个问题,git-hook工具将命令的执行权完全交个用户自定义。我们不定死命令执行的方式,而是在plugins/executors内动态指定的。 配置文件内有个executor字段,它指定执行命令的执行器,该执行器是plugins/executors目录下的js文件。例如该目录下有一个spawn.js文件,则executor设为spawn会指定该文件作为执行器。 如何自己写插件插件分为执行器插件和规范器插件,都放置在plugins的对应目录中。插件都是一个js文件,该文件表示一个node模块。 Executor插件执行器插件是真实运行命令的,一个执行器插件是一个js文件,它表示一个node模块,该模块返回一个函数。执行器插件放置在plugins/executors/目录下。一个执行器模块的典型形式是: module.exports = function ({ command, cwd, uid, gid, stderr, stdout }) { // 执行command并写入到stdout、stderr的代码} Normalizer插件规范器插件将原始的json请求体转化为工具识别的请求体。通过规范器插件,我们可以达到支持github、oschina、coding等好多不同代码托管平台的效果。 一个规范器插件是一个js文件,它表示一个node模块,该模块返回一个函数。规范器插件放置在plugins/normalizers目录下,它的典型形式是: module.exports = function ({ path, query, data, headers, request }) { return normalizedData} 开发与调试首先,复制 examples/simple-hook.yml 到 config/simple-hook.yml ,认真修改每一项。 然后,启动开发服务器: 在命令行下调用如下请求试一试: curl -XPOST http://localhost:3000/simple-hook -d '{"branch":"master", "event":"test", "token":"token"}' 未竟之志 |
请发表评论