# git-hook

**Repository Path**: davidmr/git-hook

## Basic Information

- **Project Name**: git-hook
- **Description**: git-hook旨在提供快捷、灵活、安全、可靠的WebHook体验。通过扩展插件，可以支持oschina、coding、github等任意的git代码托管平台。
- **Primary Language**: NodeJS
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7
- **Created**: 2017-05-22
- **Last Updated**: 2020-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# git-hook

git-hook是一个快速部署git代码托管平台的WebHook框架。根据灵活的插件机制，可以支持oschina、coding、github等所有的git托管平台。

git-hook旨在提供快捷、灵活、安全、可靠的WebHook体验。每台服务器只需要启动一个服务，就可以统一管理多个项目的WebHook配置。

git-hook的系统要求以及实现的功能包括：

1. 部署在Linux服务器上，基于Node；
2. 可配置token，过滤请求；
3. 提供通配符格式的分支过滤器；
4. 可配置执行命令，并绑定用户和用户组；
5. 可配置执行命令的日志文件，方便调试和排错。

## 快速上手

### 快速部署

1. 安装node依赖

        npm install

2. 启动服务（一定要以root身份）

        sudo bin/start.sh

3. 关闭或者重启服务

        sudo bin/stop.sh
        sudo bin/restart.sh

### 快速配置

在config文件夹下新建一个yaml配置文件，并记住它的名字，例如`full.yaml`。如果你对YAML格式不熟悉，请参考阮一峰的博文：[YAML 语言教程](http://www.ruanyifeng.com/blog/2016/07/yaml.html)。事实上，YAML格式是如此简单，你甚至都不用熟悉它，直接复制文件`examples/full.yaml`比照着用吧。

然后，阅读下面的表格，在`full.yaml`里配置需要的字段：

<sub>（注：字段前加`*`的是必填字段。）</sub>

字段名 | 字段解释 
 --- | ---
`*plugin` | 插件是用来解析不同托管平台的请求参数格式的，这个字段填插件名就好，例如`coding`、`oschina`、`github`等。目前，只实现了`coding`的插件。
`token` | 一般托管平台都支持token的配置，有可能字段名不一样。token的作用是对来访的Hook请求作验证，以过滤掉一些冒名的请求。如果配置了此字段，则所有的请求都必须附加token信息且信息值与配置文件的token值一致才被允许。如果没有配置此字段，默认情况是允许一切请求。
`branches` | 通配符格式的分支过滤器。可以使用通配符格式指定允许的分支。通配符很简单，例如`master`匹配master，`(master|development)`匹配master或development，`*`匹配所有。默认值是`*`。
`*command` | 将要执行的命令，它可以是任何的linux命令。
`*workingDirectory` | 每个命令执行都需要指定一个当前工作目录。这是一个必填字段，所以，即使你的命令与目录无关，都要随意配置个路径意思一下，例如`/tmp`。一个必要的前提是，在命令执行的时候，你所配置的路径是存在的且是个目录，否则命令执行会报错。
`*user` | 每个命令都需要指定一个Linux用户，用户可以是用户id或者用户名。
`*group` | 每个命令都需要指定一个Linux用户组，用户组可以是组id或者组名。
`logFile` | 记录命令标准输出和标准错误的日志文件。这样一个日志文件对于命令的执行情况和调试是很必要的。这是一个可选字段。完全可以忽略这个字段，如果你对自己的脚本执行非常有信心。

当配置完毕yaml配置文件之后，需要重启服务：

    sudo bin/startup.sh restart

最后，再到对应的代码托管平台上配置你的Hook地址。我不知道你的host地址，这里就用0.0.0.0代替。由于你的配置文件为`full.yaml`，所以你的Hook地址必须配置为：`http://0.0.0.0:3000/full.yaml`。

结束！如果你觉得这还不够简单，请提Issue。

## 高级话题

### 配置文件结构

关于配置文件，有下面的几个要点：

1. 所有配置文件都列再config文件夹下面
2. 每个配置文件都对应一个Hook配置，同时对应一个Hook地址
3. 配置文件采用YAML格式
4. `default.yaml`有特殊的功效

#### Hook名称、配置文件路径、Hook地址的对应关系

三者是严格的一一对应的关系。不妨仍以`full`举例。假设要将Hook命名为`full`，host地址为0.0.0.0，则配置文件的路径一定是`config/full.yaml`，Hook地址一定是`http://0.0.0.0:3000/full`。

此外，Hook命名的层次可以更深一点。例如将Hook命名为`dir/full`，则配置文件的路径一定是`config/dir/full.yaml`，Hook地址一定是`http://0.0.0.0:3000/dir/full`。

#### 关于`default.yaml`

`default.yaml`是个特殊的配置文件，它定义了所有其他配置文件的默认值。

### 高级配置字段

1. `commandFile`

    该字段用来指定一个脚本文件（也可以是一个二进制的可执行文件），用以执行命令。当然，你仍然可以用`command`字段配置成脚本文件的路径。然而，当你的命令是一个可执行的脚本文件时，使用`commandFile`代替`command`字段是个建议的方案，因为这能更好地和`commandFileBase`以及*约定优于配置*相结合。这些都是下面的内容了。

    `command`和`commandFile`只需要配置其一。这也就意味着，`command`不再是必填字段了。

2. Base字段

    各种路径字段，包括`workingDirectory`、`commandFile`、`logFile`等，都关联一个Base字段，如`workingDirectoryBase`、`commandFileBase`、`logFileBase`。Base字段指定了字段的查找路径，也就意味着那些非Base字段可以只用配置相对路径即可。

    在同一个文件里同时配置`*Base`字段和`非Base`字段是很蠢的行为。Base字段一般配置在`default.yaml`里，这样Hook的配置文件就继承了Base字段，这时只需要配置相对路径即可。

### 约定优于配置

我在配置文件的设计里增加了流行的约定优于配置的元素。不要问我这有什么实际的用处，我只是赶时髦而已。但是亲身体验之后，你会觉得，这确实会减少一些工作。至于减少的这些工作是否有必要，就见仁见智了。

至于约定了哪些内容呢？我还是以`full`为例吧。假设你仍然定你的Hook名称为`full`，这时，下面的约定就达成了：

1. 配置文件的路径为`full.yaml`。
2. Hook地址为`http://0.0.0.0:3000/full`，这里仍然假设你的host地址是`0.0.0.0`。
3. commandFile的默认值是`full`。
4. workingDirectory的默认值是`full`。
5. logFile可以通过布尔值来指示是否需要。如果logFile设置为`true`，则自动对应到值`full.log`。

这有什么用？如果你看到`examples/agreed.yaml`的简洁的话，你就知道这其中简化了多少工作。由于多数字段都设置好了合适的默认值，这时你只需要配置如下的字段即可：

- `token`
- `branches`
- `user`
- `group`
- `logFile: true`

此外，这些字段都可以在`default.yaml`内配置好默认值。一个最极端的情况是，只需要新建`config/full.yaml`就可以工作了。

### 插件开发指南

插件，是指各种代码托管平台适应到该框架的一个中间件。插件的具体工作，就是将发送Hook的请求数据（JSON格式），提取成框架适应的数据格式。

#### 如何编写插件

所有的插件都放在plugins文件夹下面。每个插件，都是一个Node模块。该模块导出一个函数，用以将原始的请求数据，导出为框架适应的数据格式。

    module.exports = function(originalData) {
      // ...
      return targetData
    }

参数originalData和targetData都是普通的JS对象，用以表示JSON格式。注意，切不可以用字符串类型的JSON格式。

返回值（targetData）需要包括下面的字段：

- `token`: 请求的token数据
- `branch`: 分支。分支一定要用简单的表达，如`master`、`dev`等，不能理解`ref/Heads/master`。
- `event`: 事件，如`push`等。目前框架只支持`push`，请注意小写。

一些参考示例可参考plugins目录下的`coding.js`和`simple.js`。

#### 如何引用插件

只需要在配置文件里将`plugin`字段设置成Node的模块名（相对于plugins目录），例如`coding`、`simple`即可。这时，框架会自动加载`plugins/coding.js`或`plugins/simple.js`内定义的模块。

注意，如果添加了新的插件以及旧的插件有修改，都需要重启服务。

目前，框架只提供了Coding.net的插件(coding.js)，以及用于调试的simple插件（simple.js)，其他的插件需要自主开发。

## 吐槽

请提ISSUE！

## 常见问题

持续撰写中！

## Roadmap

持续撰写中！