# tagup

**Repository Path**: satrong/tagup

## Basic Information

- **Project Name**: tagup
- **Description**: Git打标签后通过webhook在服务端自动拉代码
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 0
- **Created**: 2020-08-21
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: vcs

**Tags**: None

## README

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

- [安装](#安装)
- [命令行用法](#命令行用法)
  - [可用命令](#可用命令)
  - [start可用参数](#start可用参数)
- [API引用](#API引用)
  - [options参数](#options参数)
- [配置和使用](#配置和使用)
- [注意事项](#注意事项)



# 安装
首先确保已经安装 [Node.js](http://nodejs.org/)、 [Git](https://git-scm.com/)。

全局安装，在命令行中使用
```
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`后，在代码中可以这样使用：
```js
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`）