Metrics
0
Watch 8 Star 16 Fork 4

run27017 / git-hookNodeJS

Sign up for free
Explore and code with more than 2 million developers,Free private repositories !:)
Sign up
git-hook旨在提供快捷、灵活、安全、可靠的WebHook体验。通过扩展插件,可以支持oschina、coding、github等任意的git代码托管平台。 spread retract

Clone or download
Loading...
README.md

git-hook

git-hook是一个搭建在远端服务器上的git钩子服务,它有着远大的理想,但目前实现较为简单。现在绝大多数git仓库管理平台都支持设置一个回调URL,包括github、oschina、Coding等。当开发者在本地push代码到远程时,就会向该URL发起请求,接收该请求的服务器可以在本地运行一个配置好的命令。该工具就是用来管理这些命令的。

特性:

  • 单服务器,需要在运行命令的服务器上搭建本服务。
  • 支持多平台,包括github、oschina、coding等。
  • YAML配置文件,语法好用简洁。
  • 命令的配置支持user、group、cwd、stdout和stedrr的重定向。
  • 友好的错误提示以及日志。

快速部署

前置条件:

  1. Linux系统
  2. 已安装node和npm,node版本需要在v6及以上

部署步骤:

  1. npm install
  2. 参考配置文件规则部分
  3. 启动:sudo npm start

重启:

在任何配置文件修改的时候,都需要重启服务以重载配置。

关于sudo

服务的启动一定要加入sudo来以root身份运行。因为工具支持切换用户和用户组执行命令,只有root用户才能无缝支持用户和用户组的切换,其他身份切换都需要提供密码。当然,也可以不以root身份运行,但在配置文件内的user和group字段必须设置为当前用户和组,否则工具就会报错。

命令参数

服务器启动时支持一些参数:

  • -p/--port {port}: 端口

配置文件规则

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
}

Comments ( 0 )

You need to Sign in for post a comment

Help Search