机器人自助配置使用手册

本文档面向社区开发者，说明如何通过配置文件自助调整机器人在你的仓库中的行为，无需联系平台管理员。

1. 配置层级说明

机器人的行为由四层配置按优先级叠加决定：

层级	名称	配置文件位置	生效范围	维护人
1（最高优先级）	仓库个性配置	你的仓库的 `.infra/robot.yaml`	仅对本仓库生效，按 PR 目标分支隔离	仓库维护者
2	机器人服务仓库级默认配置	机器人服务内置	针对特定仓库的服务内置默认值	机器人服务管理员
3	组织配置	`infrastructure` 仓库 `.infra/robot.yaml`	对整个组织下未命中第 1、2 层的仓库生效	组织管理员
4（最低优先级）	机器人服务组织级默认配置	机器人服务内置	对组织下所有未命中以上三层的仓库生效	机器人服务管理员

优先级：仓库个性配置 > 机器人服务仓库级默认配置 > 组织配置 > 机器人服务组织级默认配置

仓库个性配置文件存在时，该仓库的 PR 直接使用仓库个性配置，跳过第 2、3、4 层。
仓库个性配置文件不存在，且机器人服务内置了该仓库的精确默认配置（第 2 层）时，跳过组织配置（第 3 层），直接使用机器人服务仓库级默认配置。
以上均未命中时，依次回退到组织配置（第 3 层）、机器人服务组织级默认配置（第 4 层）。
任意字段未在较高层级配置时，自动从下一层继承。

2. 仓库个性配置

2.1 配置文件位置

在你的仓库创建 .infra/robot.yaml 文件，所有可自定义的功能配置均写在这一个文件中。

2.2 按分支隔离

机器人在处理每个 PR 时，以该 PR 的目标分支为准读取配置文件。即：

合入 main 分支的 PR → 读取 main 分支的 .infra/robot.yaml
合入 release-1.0 分支的 PR → 读取 release-1.0 分支的 .infra/robot.yaml

你可以在不同分支分别维护不同的配置文件，分支之间互不影响。若某个分支上没有配置文件，该分支的 PR 将按优先级依次回退到机器人服务仓库级默认配置、组织配置、机器人服务组织级默认配置。

2.3 创建配置文件

切换到目标分支（如 main）。
在仓库创建 .infra/robot.yaml。
按第 4 节填写需要自定义的字段，只需填写想覆盖的字段，其余保持默认。
将文件提交到该分支。
等待缓存刷新后配置生效（默认 10 分钟，首次创建文件最长需等待 60 分钟）。

示例——只覆盖 lgtm 数量：

# .infra/robot.yaml
lgtm_need_nums: 2

3. 组织配置

组织配置由组织管理员统一维护，存放在组织内 infrastructure 仓库的 .infra/robot.yaml 文件中。

它的作用是为组织下所有仓库设置统一的默认值，仓库维护者无需重复配置。当某个仓库有自己的仓库个性配置时，该仓库会优先使用自己的配置，组织配置对该仓库不再生效。

格式与仓库个性配置完全相同（见第 4 节），组织管理员按需维护即可。

4. 可配置项说明

所有配置项写在同一个 .infra/robot.yaml 文件中，按需填写：

# PR 标签要求
lgtm_need_nums: 1       # 需要多少个 /lgtm
approve_need_nums: 1    # 需要多少个 /approve

# 合并方式：merge / squash / rebase
default_merge_method: merge

# PR 合入前必须存在的标签
require_labels:
  - label: lgtm
    operator: ""                      # 空：不限操作人；填写账号则只认可指定人添加的标签
  - label: approved
    operator: "operator1,operator2"

# PR 合入前必须不存在的标签（存在即阻断合入）
block_labels:
  - label: work-in-progress
  - label: needs-issue

lgtm_need_nums

控制 PR 合入需要多少个 /lgtm，默认值由社区管理员在机器人服务中配置。

approve_need_nums

控制 PR 合入需要多少个 /approve，默认值由社区管理员在机器人服务中配置。

default_merge_method

设置 PR 的合并方式：

值	含义
`merge`	保留所有提交历史
`squash`	将所有提交压缩为一个提交再合入
`rebase`	以变基方式合入，保持线性历史

require_labels

列出 PR 合入前必须存在的标签。每条规则包含：

label：标签名，精确匹配。
operator：指定哪些账号添加的该标签才被认可，逗号分隔多个账号，留空表示不限制操作人。

ℹ️说明： operator 只影响机器人判断标签是否"合规"，不影响平台本身的标签操作权限。

block_labels

列出 PR 合入前必须不存在的标签。若 PR 上存在任意一个阻断标签，机器人将拒绝合入。

operator：留空表示任何人添加的该标签都会触发阻断；填写账号则只有指定人添加的该标签才触发阻断。

5. 生效范围与时间

生效范围

配置类型	生效范围
仓库个性配置	仅对本仓库、以该分支为目标分支的 PR 生效
组织配置	对整个组织下没有仓库个性配置的所有仓库生效

生效时间

场景	等待时间
修改已有配置文件	最长 10 分钟
首次创建配置文件（该分支原本没有配置文件）	最长 60 分钟

缓存到期后，机器人在处理下一个 PR 事件时会自动读取最新配置，无需额外操作。

6. FAQ

Q：修改配置后机器人没有变化？

A：请检查以下几点：

文件是否提交到了正确的分支（应与 PR 目标分支一致）。
文件路径是否为 .infra/robot.yaml。
YAML 格式是否有误（可使用在线 YAML 校验工具检查）。
是否还在缓存期内（修改后最长等 10 分钟，首次创建最长等 60 分钟）。

Q：没有配置文件的分支会受影响吗？

A：不会。目标分支没有 .infra/robot.yaml 时，该分支的 PR 不受仓库个性配置影响，自动回退到组织配置或机器人服务默认配置（仓库级或组织级）。

Q：operator 留空和不填有什么区别？

A：效果相同，都表示不限制操作人，任何有标签操作权限的人添加的标签都被认可。

Q：可以只配置部分字段吗？

A：可以。只需填写想覆盖的字段，未填写的字段自动继承组织配置或机器人服务默认值。例如只想修改合并方式：

default_merge_method: squash