Tagup

Tagup 是一款简易的Webhook工具，通过添加标签(tag)实现在服务端自动更新(克隆)代码。简单配置即可运行。支持GitHub, GitLab, Gitee, Gogs, Gitea。

• 安装
• 命令行用法
  • 可用命令
  • start可用参数
• API引用
  • options参数
• 配置和使用
• 注意事项

安装

首先确保已经安装 Node.js、 Git。

全局安装，在命令行中使用

npm i tagup -g

当做程序依赖包使用

npm i tagup

命令行用法

tagup [command] [options]

例如：

tagup start -d /home/foo -p 8000

可以通过 tagup -h 查看可用参数。

可用命令

  -v, --version           显示版本
  start [options]         启动tagup服务
  stop <id>               停止tagup
  list                    查看正在运行的tagup服务列表
  help [start|stop|list]  显示命令可用参数

start可用参数

tagup start -h:

  -f, --file <type>      通过配置文件启动服务，通过require获取文件内容(支持json、js)
  -i, --id <type>        启动服务的唯一标识，默认自动生成
  -d, --dir <type>       仓库所在的根目录（绝对路径）（必填项）
  -p, --port <type>      启动服务的端口，默认自动选择
  -s, --secret <type>    Webhook中设置的秘钥
  -U, --username <type>  git登录用户名（通过http克隆代码）
  -P, --password <type>  git登录密码（通过http克隆代码）
  -pa, --path <type>     URL的路径，默认：/webhook
  -c, --cmd <type>       获取代码并切换到对应的标签后执行的命令
  -D, --daemon           开启常驻进程和守护进程
  -h, --help             显示可用命令

API引用

通过NPM安装tagup后，在代码中可以这样使用：

const tagup = require('tagup');

// 或者在typescript中
// import tagup from 'tagup';

const options = {
  dir: '/home/foo',
  port: 8000
};

tagup(options);

options参数

• dir: 仓库存放的目录，必须是绝对路径。必选参数
• port: 启动服务的端口，默认自动选择
• secret: Webhook中设置的秘钥
• username: git登录用户名（通过http克隆代码）
• password: git登录密码（通过http克隆代码）
• path: URL的路径，默认：/webhook
• cmd: 获取代码并切换到对应的标签后执行的命令

配置和使用

下面以GitHub为例：

• 在服务端启动服务 tagup -d /home/foo -p 8000 -s 123456
• GitHub的配置
  1. 进入GitHub项目中的 Settings - Webhooks - Add webhook
  2. 在Payload URL中输入 http(s)://ip:8000/webhook (ip为启动的服务所在的服务器的ip，如果使用了代理则输入代理的地址。必须确保URL路径为 /webhook)
  3. 在Secret中输入 123456
  4. 在自定义事件中勾选Branch or tag creation （确保有Tag push event）
  5. 勾选 Active
  6. 点击 Add webhook 保存
• 服务端关于Git相关的配置
  1. 确保仓库存放的目录(dir)有写入权限
  2. 确保服务端已安装 Git，如果使用ssh拉取代码还需要确保已安装 OpenSSH
  3. 如果使用ssh拉取代码，则需要确保已配置 SSH key（配置好后最好先尝试执行一下git clone [url]）
  4. 如果使用http拉取代码，则启动服务时确保已配置username和password
  5. 如果未配置username和password，会执行git clone url

注意事项

1. 使用username和password后，会使用http或https方式获取代码，此时会将username和password拼入url中，并且克隆的项目中 .git/config 文件中可以查看到账号密码。
2. 添加标签的格式必须是 v1.0 或 v1.2.3 或 v1.2.3.4
3. tagup 会检测项目中是否包含package.json文件，如果存在且有未安装的依赖则会执行 npm install，之后再执行参数cmd中的命令（如果cmd参数不存在则会检测package.json中的scripts中是否包含restart，如果存在则执行npm run restart）