CANN 社区机器人自助配置指南：基于 `.infra/robot.yaml` 的四层配置体系与 PR 合入门槛实战

CANN 社区机器人自助配置指南基于.infra/robot.yaml的四层配置体系与 PR 合入门槛实战【免费下载链接】infrastructure本仓库用于托管CANN社区基础设施团队的公开信息包括不限于会议日程成员信息服务文档和配置等信息项目地址: https://gitcode.com/cann/infrastructure本文是一份面向 CANN 社区开发者的机器人自助配置手册核心讲解如何通过仓库内的.infra/robot.yaml配置文件自主调整机器人在 PR 合入前的行为如/lgtm、/approve数量要求、必须/禁止存在的标签、合并方式无需联系平台管理员。读完本文你将掌握机器人四层配置的优先级与回退规则、按 PR 目标分支隔离的配置机制、全部可配置项的字段含义与取值范围以及配置生效时间与常见排障方法。1. 配置要解决什么问题先理解机器人在 PR 流程中扮演的角色在 CANN 社区中所有项目均由 Bot 维护开发者可以在每个 Pull Request 或 Issue 下通过评论触发机器人命令机器人据此自动打标签、执行检查并最终合入 PR。相关命令及行为可参考 机器人使用指南 与 机器人能力列表核心交互包括命令作用影响标签/lgtm、/lgtm cancel评审通过 / 取消评审通过添加或移除lgtm标签/approve、/approve cancel同意合并 / 取消同意合并添加或移除approved标签/merge分支守护者branch_keeper同意合并添加keeper_approved标签/check-pr检查 PR 标签是否满足条件满足则合并触发合并动作/check-cla强制检查 CLA 签署状态cann-cla/yes或cann-cla/no/compile触发 CodeArts 编译流水线ci-pipeline-passed或ci-pipeline-failed从能力列表可以看到机器人的核心逻辑是**“标签即状态”**评审通过、同意合并、CI 通过等都通过标签表达机器人依据标签集合判断一个 PR 是否满足合入条件。而本手册要解决的正是“这些合入条件如何按仓库、按分支自助定制”的问题——通过.infra/robot.yaml配置文件仓库维护者可以精确控制需要多少个/lgtm、多少个/approve才放行合入前必须存在哪些标签、必须不存在哪些标签采用哪种合并方式merge / squash / rebase。此外机器人还有另一类面向 Issue 的自动处理规则已解决识别、stale 标记、超期关闭等这类规则由社区在 bot-issue-manage.yaml 中集中维护属于“机器人服务内置配置”的典型样例详见本文第 8 节可作为理解配置体系的对照。2. 四层配置体系与优先级机器人的行为由四层配置按优先级叠加决定从高到低依次为层级名称配置文件位置生效范围维护人1最高优先级仓库个性配置你的仓库的.infra/robot.yaml仅对本仓库生效按 PR 目标分支隔离仓库维护者2机器人服务仓库级默认配置机器人服务内置针对特定仓库的服务内置默认值机器人服务管理员3组织配置infrastructure仓库.infra/robot.yaml对整个组织下未命中第 1、2 层的仓库生效组织管理员4最低优先级机器人服务组织级默认配置机器人服务内置对组织下所有未命中以上三层的仓库生效机器人服务管理员优先级仓库个性配置 机器人服务仓库级默认配置 组织配置 机器人服务组织级默认配置各层级之间的回退逻辑如下仓库个性配置文件存在时该仓库的 PR 直接使用仓库个性配置跳过第 2、3、4 层。仓库个性配置文件不存在且机器人服务内置了该仓库的精确默认配置第 2 层时跳过组织配置第 3 层直接使用机器人服务仓库级默认配置。以上均未命中时依次回退到组织配置第 3 层、机器人服务组织级默认配置第 4 层。任意字段未在较高层级配置时自动从下一层继承——这是“按需填写、只覆盖想覆盖的字段”这一使用方式的底层机制。也就是说配置是按字段粒度继承的一个仓库可以只覆盖lgtm_need_nums其余字段如approve_need_nums、default_merge_method、require_labels、block_labels仍从组织配置或机器人服务默认值继承不会因“部分覆盖”而整体失效。3. 仓库个性配置.infra/robot.yaml3.1 配置文件位置在你的仓库根目录创建.infra/robot.yaml文件所有可自定义的功能配置均写在这一个文件中。注意路径中的目录为.infra隐藏目录文件名固定为robot.yaml。3.2 按 PR 目标分支隔离机器人在处理每个 PR 时以该PR 的目标分支为准读取配置文件合入main分支的 PR → 读取main分支的.infra/robot.yaml合入release-1.0分支的 PR → 读取release-1.0分支的.infra/robot.yaml。这意味着你可以在不同分支分别维护不同的配置文件分支之间互不影响。例如main分支要求 1 个/lgtm而正式发布分支release-1.0要求 2 个/lgtm两者可独立配置、同时生效。若某个分支上没有配置文件该分支的 PR 将按第 2 节的优先级依次回退到机器人服务仓库级默认配置、组织配置、机器人服务组织级默认配置。3.3 创建配置文件的步骤切换到目标分支如main。在仓库创建.infra/robot.yaml。按第 5 节填写需要自定义的字段只需填写想覆盖的字段其余保持默认。将文件提交到该分支。等待缓存刷新后配置生效默认 10 分钟首次创建文件最长需等待 60 分钟。3.4 最小示例只覆盖 lgtm 数量# .infra/robot.yaml lgtm_need_nums: 2该示例只修改了/lgtm的数量要求从默认值改为 2其余字段approve_need_nums、default_merge_method、require_labels、block_labels均未填写将自动继承组织配置或机器人服务默认值。4. 组织配置为整个组织设定统一默认值组织配置由组织管理员统一维护存放在组织内infrastructure仓库的.infra/robot.yaml文件中。它的作用是为组织下所有仓库设置统一的默认值仓库维护者无需重复配置。例如组织希望所有仓库默认要求 1 个/approve、默认禁止work-in-progress标签只需在组织配置中写一次即可。当某个仓库有自己的仓库个性配置时该仓库会优先使用自己的配置组织配置对该仓库不再生效。组织配置的格式与仓库个性配置完全相同见第 5 节组织管理员按需维护即可。可以这样理解两者的分工仓库个性配置解决“单个仓库、单个分支”的特殊需求粒度最细组织配置解决“组织内所有仓库”的共性需求作为兜底默认值减少仓库维护者的重复配置成本。5. 可配置项详解所有配置项写在同一个.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-issue5.1lgtm_need_nums控制 PR 合入需要多少个/lgtm。机器人在统计时会按“标签合规规则”见require_labels的operator说明认定有效标签数量达到该数值后才视为评审通过条件满足。类型整数默认值由社区管理员在机器人服务中配置对应第 2 层或第 4 层内置默认值建议与仓库评审制度的实际要求对齐例如正式发布分支可设置更高的值。5.2approve_need_nums控制 PR 合入需要多少个/approve语义与lgtm_need_nums相同。类型整数默认值由社区管理员在机器人服务中配置。在 CANN 社区的默认实践中一般每个模块需要 1 个 committer/maintainer 评论/lgtm和 1 个 committer 评论/approve详见 机器人使用指南而本配置项允许仓库在此基础上按需提高或降低门槛。5.3default_merge_method设置 PR 的合并方式可选值如下值含义merge保留所有提交历史squash将所有提交压缩为一个提交再合入rebase以变基方式合入保持线性历史选择说明追求完整历史审计信息 →merge追求主干整洁、单 PR 单提交 →squash追求严格线性历史、便于二分定位 →rebase。需要留意的是社区默认行为中/approve通常采用 squash 合并方式参见 机器人使用指南 的命令表说明若仓库需要统一其他合并策略可通过本字段覆盖。另外若仓库在平台侧将 PR 合并模式设置为仅允许 fast-forward 合并则即使配置为merge或squash机器人也会按平台约束提示开发者先 rebase该场景的排障说明同样见 机器人使用指南。5.4require_labels列出 PR 合入前必须存在的标签。每条规则包含两个字段label标签名精确匹配需与仓库中实际存在的标签一致operator指定哪些账号添加的该标签才被认可逗号分隔多个账号留空表示不限制操作人。示例解读require_labels: - label: lgtm operator: # 任何有权限的人添加的 lgtm 都认可 - label: approved operator: operator1,operator2 # 只有 operator1、operator2 添加的 approved 才认可注意事项operator只影响机器人判断标签是否“合规”不影响平台本身的标签操作权限非机器人账号手动添加的标签默认不会被机器人认可为“满足条件”详见 机器人使用指南 中“The following labels are not ready...” 的 FAQ因此配置require_labels时建议配合机器人指令/lgtm、/approve触发打标。5.5block_labels列出 PR 合入前必须不存在的标签。若 PR 上存在任意一个阻断标签机器人将拒绝合入。label标签名精确匹配operator留空表示任何人添加的该标签都会触发阻断填写账号则只有指定人添加的该标签才触发阻断。典型用法用work-in-progress标识开发中的 PR、用needs-issue标识缺少关联 Issue 的 PR只要这些标签存在无论其他条件是否满足机器人都不会合入。这与社区中“PR 标题以[WIP]开头则无法合入”的机制见 机器人使用指南是互补的两道防线一个是标题约束一个是标签约束。5.6 字段粒度继承小结本节 5 个配置项中任意一项未填写都会自动从下一层组织配置或机器人服务默认配置继承。因此最佳实践是只写本仓库确实需要差异化的字段把通用默认值交给组织配置统一维护避免每个仓库各自维护一份冗长且容易漂移的完整配置。6. 生效范围与生效时间6.1 生效范围配置类型生效范围仓库个性配置仅对本仓库、以该分支为目标分支的 PR 生效组织配置对整个组织下没有仓库个性配置的所有仓库生效6.2 生效时间场景等待时间修改已有配置文件最长 10 分钟首次创建配置文件该分支原本没有配置文件最长 60 分钟说明机器人采用缓存机制读取配置缓存到期后机器人在处理下一个 PR 事件时会自动读取最新配置无需额外操作也不需要重启服务或联系管理员。7. 常见问题排查FAQQ修改配置后机器人没有变化A请按以下顺序检查文件是否提交到了正确的分支应与 PR 目标分支一致文件路径是否为.infra/robot.yamlYAML 格式是否有误可使用在线 YAML 校验工具检查是否还在缓存期内修改后最长等 10 分钟首次创建最长等 60 分钟。Q没有配置文件的分支会受影响吗A不会。目标分支没有.infra/robot.yaml时该分支的 PR 不受仓库个性配置影响自动回退到组织配置或机器人服务默认配置仓库级或组织级。因此新增分支、或者忘记在某个分支提交配置都不会导致该分支的 PR 被“卡死”——它们会安静地使用较低层级的默认值。Qoperator留空和不填有什么区别A效果相同都表示不限制操作人任何有标签操作权限的人添加的标签都被认可。只有当需要“仅认可指定人添加的标签”时才需要显式填写账号。Q可以只配置部分字段吗A可以。只需填写想覆盖的字段未填写的字段自动继承组织配置或机器人服务默认值。例如只想修改合并方式default_merge_method: squash8. 仓库内机器人配置的实战对照bot-issue-manage.yaml为了帮助你更直观地理解“配置文件如何驱动机器人行为”这里补充仓库中真实存在的一份机器人配置样例bot-issue-manage.yaml。它对应机器人能力列表见 机器人能力列表中的Issue 自动处理规则已解决识别、stale 闲置标记、wait-feedback 等待反馈闭环与本文的.infra/robot.yaml分别管理两类行为配置对象配置文件管理的机器人行为PR 合入门槛各仓库.infra/robot.yaml本文主题lgtm/approve 数量、合并方式、标签要求Issue 自动处理config/bot-issue-manage.yaml超时打标、评论提醒、自动关闭该文件的结构与本文第 5 节一脉相承同样分为几类配置bot-issue-manage: # 标签名称配置 label_resolve: resolved label_stale: stale label_wait_feedback: wait-feedback # 时间配置天 resolve_to_stale_days: 7 stale_to_close_days: 14 wait_feedback_to_warn_days: 7 wait_feedback_to_close_days: 14 # 评论内容 stale_comment: ... wait_feedback_warn_comment: ... wait_feedback_close_comment: ...从中可以归纳出机器人配置文件的通用要素对编写.infra/robot.yaml同样适用标签必须真实存在配置中引用的标签resolved、stale、wait-feedback以及.infra/robot.yaml中的lgtm、approved、work-in-progress等必须已在目标仓库中创建否则机器人无法成功执行打标动作时间/数量类参数是机器人的核心阈值Issue 规则中的resolve_to_stale_days: 7、stale_to_close_days: 14与.infra/robot.yaml中的lgtm_need_nums本质相同——都是机器人判定是否执行动作的数值门槛文本内容同样可配置评论内容、预警文案等均可随配置调整无需改代码。此外从 机器人能力列表 的“规则新增与维护说明”可以看到该配置文件的维护流程修改配置 → 提交 PR 到对应代码仓 → PR 合入后机器人配置在每轮任务执行前自动刷新生效。这与本文第 6 节“缓存到期后自动读取最新配置”的机制一致说明配置驱动 自动刷新是 CANN 机器人体系的统一设计思路。总结CANN 社区机器人通过四层配置体系仓库个性配置 机器人服务仓库级默认配置 组织配置 机器人服务组织级默认配置实现了“默认值集中管理、特殊情况按仓库按分支定制”的灵活治理普通仓库维护者只需在目标分支创建.infra/robot.yaml按需覆盖lgtm_need_nums、approve_need_nums、default_merge_method、require_labels、block_labels等字段即可自助调整 PR 合入门槛无需联系平台管理员未填写的字段自动继承上级配置配合最长 10 分钟首次创建最长 60 分钟的缓存刷新机制配置变更轻量且低风险仓库内已有的 bot-issue-manage.yaml 展示了同类配置文件的真实写法与维护流程可作为编写和评审配置的参考模板。【免费下载链接】infrastructure本仓库用于托管CANN社区基础设施团队的公开信息包括不限于会议日程成员信息服务文档和配置等信息项目地址: https://gitcode.com/cann/infrastructure创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考