README
Tagup
Tagup 是一款简易的Webhook工具,通过添加标签(tag)实现在服务端自动更新(克隆)代码。简单配置即可运行。支持GitHub, GitLab, Gitee, Gogs, Gitea。
安装
全局安装,在命令行中使用
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的路径,默认:/webhookcmd
: 获取代码并切换到对应的标签后执行的命令
配置和使用
下面以GitHub为例:
- 在服务端启动服务
tagup -d /home/foo -p 8000 -s 123456
- GitHub的配置
- 进入GitHub项目中的
Settings
-Webhooks
-Add webhook
- 在Payload URL中输入
http(s)://ip:8000/webhook
(ip为启动的服务所在的服务器的ip,如果使用了代理则输入代理的地址。必须确保URL路径为/webhook
) - 在Secret中输入
123456
- 在自定义事件中勾选
Branch or tag creation
(确保有Tag push event) - 勾选
Active
- 点击
Add webhook
保存
- 进入GitHub项目中的
- 服务端关于Git相关的配置
- 确保仓库存放的目录(
dir
)有写入权限 - 确保服务端已安装 Git,如果使用ssh拉取代码还需要确保已安装 OpenSSH
- 如果使用ssh拉取代码,则需要确保已配置 SSH key(配置好后最好先尝试执行一下
git clone [url]
) - 如果使用http拉取代码,则启动服务时确保已配置
username
和password
- 如果未配置
username
和password
,会执行git clone url
- 确保仓库存放的目录(
注意事项
- 使用
username
和password
后,会使用http或https方式获取代码,此时会将username
和password
拼入url中,并且克隆的项目中 .git/config 文件中可以查看到账号密码。 - 添加标签的格式必须是
v1.0
或v1.2.3
或v1.2.3.4
- tagup 会检测项目中是否包含package.json文件,如果存在且有未安装的依赖则会执行
npm install
,之后再执行参数cmd
中的命令(如果cmd
参数不存在则会检测package.json中的scripts中是否包含restart
,如果存在则执行npm run restart
)