# robot-operating-guide

**Repository Path**: YwHql/robot-operating-guide

## Basic Information

- **Project Name**: robot-operating-guide
- **Description**:  gitee机器人服务使用指南
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2023-02-13
- **Last Updated**: 2025-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitee机器人服务使用指南

## 背景

机器人服务已平稳运行于gitee平台的个别社区，为社区仓库的PR提供review引导、标签添加、PR合入、消息通知、过期清理等操作。

为方便新的社区/仓库接入机器人服务，并根据自身的需求情况，选择合适的机器人。现对机器人服务架构以及各个机器人的功能和使用方法作个详细的介绍。


适用业务：gitee平台PR处理

针对读者：社区/仓库管理员

## 工作原理
当代码仓库发生代码推送、新建PR、创建标签、用户评论等事件时，gitee平台会自动回调一个设定的 http 地址。机器人监听该回调即可做出不同逻辑的业务操作。

配置方式、详情可参考官方文档[《Gitee WebHook 文档》](https://gitee.com/help/categories/40)

## 架构总览


```mermaid
graph TD
C[gitee平台] --> A
A[robot-gitee-hook-delivery]
A --> D[kafka]
D --> E[robot-hook-dispatcher]
E --> F[robot-gitee-access]
F --> I[robot-A]
F --> K[robot-B]
F --> J[robot-X]
```
机器人服务整体架构如上图所示，所有的机器人均采用golang语言开发。

机器人服务以一个社区为单位，不同的社区需独立搭建一套机器人服务。


### robot-gitee-hook-delivery
由于一个仓库包含多种事件，需要多个机器人根据不同事件进行不同的业务逻辑处理，因此不能直接在gitee上配置业务逻辑处理机器人的回调地址，必须有统一的回调地址，这就是robot-delivery的作用。

robot-gitee-hook-delivery将收到的所有事件放入kafka消息队列。

当社区事件较多，robot-gitee-hook-delivery处理能力不足时，可进行水平扩展。

[《robot-gitee-hook-delivery使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-delivery.md)

### robot-hook-dispatcher

robot-hook-dispatcher机器人从kafka消费信息，并向下分发，期间控制下发速度，防止下游机器人处理能力不足导致消息丢失，这也是该机器人的核心功能。

因此robot-hook-dispatcher就不能进行水平扩展，这也导致必须和robot-gitee-hook-delivery分开部署。

[《robot-hook-dispatcher使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-dispatcher.md)

### robot-gitee-access

robot-gitee-access的作用是根据配置把不同的事件消息分发到指定的机器人，如robot-A,robot-B,robot-X等等，这些才是处理具体业务逻辑的机器人。

该机器人是架构升级前已经存在的旧机器人，升级后直接沿用，这样也使各机器人更加权责分明。

[《robot-gitee-access使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-access.md)

## 接入准备

### 添加robot为管理员

选取一个账号作为机器人账号，机器人通过该账号对PR进行相关操作。由于PR合入、添加标签等操作需要较高权限，需要将机器人账号设置为仓库的管理员。

每个需要接入机器人的代码仓库都需要添加机器人账号为管理员。

### 获取robot私人令牌

机器人通过上述账号对PR操作的方式是直接调用gitee官方的Open API，调用API接口时需要机器人账号的私人令牌，这样可绕过账号密码的方式直接使用机器人账号。

获取私人令牌的方式在个人设置页面，创建令牌时注意权限的选择。
![image](https://gitee.com/YwHql/robot-operating-guide/raw/master/images/create_token.png)


## 必选机器人

### 基础架构机器人

如上文所述，robot-gitee-hook-delivery，robot-hook-dispatcher和robot-gitee-access属于架构所需的机器人，**必须存在**。

### robot-cla

CLA，全称 Contributor License Agreement（贡献者许可协议），该协议授予著作权和专利许可给拥有该软件知识产权的公司或组织，可在今后避免诸多的法律纠纷。

该协议以社区为单位进行签署，只需签署一次，之后对该贡献者在该社区的所有PR提交都生效。

而robot-cla就是检查提交PR的用户是否已经签署了对应社区的CLA，已签署CLA是PR合入的必要条件。

[《CLA签署指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/signcla.md)

[《robot-cla使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-cla.md)

## 可选机器人

### robot-review-trigger
该机器人以评论的方式给PR作者进行提示，引导完成review过程，并给PR打上对应的标签。

该机器人通常与robot-tide配合使用。

[《robot-review-trigger使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-review-trigger.md)

### robot-gitee-tide
该机器人检查PR是否已经具备指定的标签，如果是则自动合入PR。

该机器人通常与robot-review-trigger配合使用。

[《robot-gitee-tide使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-tide.md)


### robot-gitee-assign
该机器人监听Pull Requests和Issues的评论内容里的特定指令，执行分配/取消审查人、协作者操作

[《robot-gitee-assign使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-assign.md)

### robot-gitee-label
用户可以使用一些命令添加和移除issue与PullRequest标签；此外还会监听PR改变的事件，根据配置自动移除指定的标签以及检测标签是否有效。

[《robot-gitee-label使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-label.md)

### robot-gitee-lifecyle
该机器人监听评论内容里的特定指令关闭一个Pull Request或者Issue，重新打开Issue。

[《robot-gitee-lifecyle使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-lifecyle.md)

### robot-gitee-scavenger
该机器人负责清理长期未被合入的PR，超过一定时间就会被关闭。

[《robot-gitee-scavenger使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-scavenger.md)

### robot-gitee-welcome
机器人在用户创建issue 或 pull request的时候会添加欢迎评论内容

[《robot-gitee-welcome使用指南》](https://gitee.com/YwHql/robot-operating-guide/blob/master/docs/robot-welcome.md)