文档

指令

一页内容说明CoRoid无需人工干预即可执行的操作,展示其已完成的任务,并允许你暂停它。

这是指令是您无需人工干预即可指定CoRoid可执行操作的地方。它在导航栏中有专属入口,位于“Quality Control”旁边,包含两个部分:概览会告知您当前已设置的规则,而设置则是您修改规则的位置。

概览页展示的内容

概览页仅回答一个问题:CoRoid无需您干预就能执行哪些操作?

它首先会给出一句话说明,例如“CoRoid会自动启动安全补丁修复工作,且正在学习在后台合并代码。其余步骤均需等待您的指令。”如果CoRoid还能自行修复或拦截拉取请求,第二行也会说明这一点。其下方会按工作流程顺序列出“指令”确定的四个步骤:

步骤含义
开始工作CoRoid会在您的某个目标下启动无人指定的工作任务。
合并CoRoid会合并一个pull request。
部署CoRoid会将代码部署到对应环境。
回滚CoRoid会撤销失败的部署操作。

每个步骤都会标注以下其中一种状态:

  • 需征求您的许可。无相关授权覆盖该操作,因此由人工执行。
  • 在后台学习。有授权覆盖该操作,但仅记录其原本要执行的内容。步骤中会注明生效时间及截至目前已执行的操作。
  • 由系统自行执行。有生效的授权覆盖该操作,步骤中会注明对应的工作内容及通知方式。
  • 被CoRoid中止。CoRoid自行中止了该步骤对应的授权。点击可查看原因。
  • 仅限安全补丁修复(开始工作):CoRoid会在“安全”模块的设置下启动安全补丁修复工作,其余操作均由人工执行。

可在“设置”中打开对应步骤的授权,或为该步骤创建新授权。

步骤下方:

  • 始终由人工决策:受保护路径以及CoRoid在某个项目中保持开放的拉取请求数量。无论授权如何设置,受保护路径的更改绝不会由CoRoid合并或部署。
  • 目标:CoRoid的工作方向、可支配资源以及相关工作的最终去向。
  • 项目:暂停或授权受限的项目会单独列为一行,其余项目则跟随组织设置。

所有者和管理员可在概览页顶部暂停自动化功能。

进行设置

  1. 打开指令 → 设置并选择从预设模板开始,或者新建 授权以配置单个步骤的授权。
  2. 该授权初始处于后台运行模式。可让其在实际工作中运行一段时间。
  3. 打开授权后可查看其原本要执行的操作。若相关内容令您信服,可选择设为生效。
  4. 如果想在 Slack 或 Telegram 中接收相关通知,请为CoRoid的功能位于设置 → 连接 → 通知路由。

您可随时将授权切换回后台模式,或暂停自动化功能。

设置

“设置”页面首先展示组织级配置,随后是每个项目的配置。每行会显示当前已设置的规则;点击该行可在侧边面板中打开编辑器。页面本身不支持直接编辑。

分组行
自主权限暂停,包含所有挂起和暂停状态;还有恢复预留区
授权每个授权对应一行,包含从预设模板开始和新建授权
目标每个目标对应一行,包含新建目标
限制受保护路径、交付操作、开放中的拉取请求、智能体
历史记录对“指令”的所有更改以及基于此做出的决策。

项目页面会单独展示该项目的暂停状态、各授权情况以及历史记录。目标和限制属于组织级配置。

授权

一个授权指CoRoid无需人工干预即可执行的操作。其对应行会标注名称,例如“合并人工指定的工作”,同时会说明其覆盖范围:

分级为低优先级,适用于所有项目,每日最多执行5次。它会先通知您,并等待10分钟以便您发出停止指令。

在对应面板中可逐部分编辑:操作步骤、适用的工作范围、涵盖的变更风险等级、涉及的项目、限制条件、排除的路径以及通知方式。

可部署的授权还能限制单次部署的变更范围:即一次发布中允许CoRoid部署的已合并拉取请求数量。规模较大的发布由人工部署,这样就不会出现因整体失败而导致生产环境部署中断的情况。

一项授权覆盖四个步骤中的某一个,或是覆盖CoRoid在拉取请求上执行的两类操作之一:

  • 修复拉取请求。当CoRoid自身工作的pull request上检查未通过时,CoRoid会启动一轮修复流程。若没有针对该工作的授权,它会将故障留给审核人员处理。若你自行选择“修复未通过的检查”,则无需授权。
  • 阻塞拉取请求。当CoRoid审核模块发现必须修复的问题时,它会要求做出变更,因此pull request会等待人工处理。若项目没有对应授权,审核结果仅会作为评论呈现,且不会导致检查失败。阻塞授权会覆盖该项目下的所有pull request,无论其由谁创建、风险等级如何,除非涉及授权排除的路径。

这两类操作在成为授权前,CoRoid就已经能执行了。每个组织都将它们设为生效授权,因此成为决策项后并无实质变化:将其限定为特定项目或撤销授权后,CoRoid便会停止相关操作。暂停也会终止这些操作。

授权的面板仅展示其对应步骤所需的内容。启动工作、修复和回滚操作在等级变更前就已确定,因此不存在风险等级或排除路径的设置。阻塞授权没有“所属工作”的概念:它覆盖所有的pull request。

CoRoid不再询问是否执行相关工作:启动工作本身就是当下的决策。针对执行的授权会明确说明这一点,且可被撤销。

授权初始处于影子状态

新创建的授权不具任何效力。在影子状态下,CoRoid会记录该授权原本允许的操作,以便你在依赖它之前查看相关内容。设为生效即可使其正式生效。

若编辑内容使授权权限扩大,已生效的授权会退回影子状态;若仅缩小授权范围,则不会如此。

其原本可执行的操作

打开授权即可查看:

  • CoRoid请求该授权的频率,以及影子状态下它原本允许的操作;
  • 对于具备合并功能的授权,可查看过去30天内的数据:此类工作对应的拉取请求合并数量、授权本可合并的数量、其余请求未合并的原因,以及原本会被授权合并但后续被回滚、修复或跟进的每一个请求;
  • 授权生效前需满足的条件。

针对评级为低等级的变更的授权无需额外条件:规则已直接给定该等级。针对评级为中等级的变更的授权依赖模型判定,因此仅在满足记录条件时才生效:至少30个同类别且未被误判为通过的已审核拉取请求,以及至少10个已被阻塞的不良变更请求。在此之前,授权会提示还缺少哪些条件。

从预设模板开始

从预设模板开始会用一组授权填充指令字段,所有授权均处于影子状态:

预设模板新增内容
修复根据目标开展相关工作
合并修复,并在等级评定为低时合并相关成果
发布合并成果,并部署到你指定的环境中
闭环管理发布成果,若部署失败则回滚该环境
保持依赖项最新合并评级为低级别的依赖更新

预设模板不会让授权生效,也不会添加你已有的任何授权。

项目可以缩小指令范围

组织的授权是每个项目的默认设置。在项目页面上,可选择某个授权以针对该项目禁用它、降低其级别、缩小其限制范围或添加排除路径。项目无法获得超出组织授予范围的权限。

当CoRoid自行暂停某授权时

  • 已暂停。CoRoid的审核人员或风险评定规则发生变化,而该授权尚未基于新规则完成评估。满足条件后,它会自动重新生效。
  • 因熔断机制被暂停。该授权允许合并的请求,后续被回滚、修复或跟进的频率高于同一项目中人工发起的合并请求。单次故障不会导致此结果。授权会同时显示两类请求的数量。人工可解除暂停状态并说明原因。

授权可合并的内容

具备合并功能的授权会注明其覆盖的工作范围。它仍仅覆盖评级等于或低于其级别的变更。

工作覆盖内容
用户需求对应的工作用户提出需求后,由CoRoid为该任务创建的pull request
目标导向下的工作根据你设定的目标,由CoRoid启动的pull request
依赖项更新由Dependabot或Renovate生成的pull request(在GitLab中,指由项目或群组的访问令牌机器人从分支发起的合并请求),用于更新npm包,每个包均为同一版本线的补丁版或小版本,发布时间不少于7天,无新的安装脚本,且锁文件与之匹配renovate/分支)会将 npm 包分别更新到同一版本线上的补丁或次要版本,这些版本至少已发布 7 天,且没有新增安装脚本,锁文件与package.json,且没有未关闭的安全通告。此类更新在满7天后会被评为低风险。
可信人员由授权成员创建的pull request,其基准之后的所有提交均由该成员关联的GitHub账号撰写并提交,且GitHub已验证其签名。在GitLab上,该成员关联的GitLab账号会发起合并请求,此时GitLab会验证每个提交的签名,且每个提交的作者和提交者邮箱均为该成员在GitLab上确认过的邮箱。通过网页编辑器提交的提交,或由他人推送的提交,需由人工处理。

授权如何合并

Factory中的合并计划会将授权覆盖的pull request置于CoRoid现在可以合并,随后合并列队会将其合并。合并瞬间,CoRoid会再次查询指令,因此暂停、搁置、额度耗尽或计划制定后出现的新提交都会中断合并流程。

合并提交会标注授权及其版本号。此次合并会计入授权的统计中,对授权指定的负责人而言,也会记录在历史记录和授权限额内。

在后台,合并计划会指示授权将合并pull request,最终由人工决定。

通知与停止

授权会说明其如何向您通知合并事宜:

  • 首先通知,然后等待停止指令。当合并列队处理该拉取请求时,授权的负责人及发起该工作的人员会收到通知。窗口期结束后(例如10分钟),CoRoid会执行合并,除非有人点击停止通知中或合并计划里的按钮,或者若已关联账号,点击Slack或Telegram上的对应帖子。被停止的pull request将等待人工干预。
  • 每次之后。合并完成后会通知您。

关联您的账号

针对可信人员的授权以及CoRoid审批功能,需要知晓哪个GitHub或GitLab账号属于您。Slack或Telegram中的停止功能也需要识别您的Slack或Telegram账号。在个人资料 → 关联账号,逐一关联即可,平台会予以确认。CoRoid仅保存账号的ID和名称,不会存储令牌。对于GitLab,还会保存您在该平台确认的各邮箱的摘要(非邮箱本身),以此判断提交是否来自您;添加新邮箱后需重新关联。取消关联会删除所有关联信息。若您的组织接入了自管理的GitLab,在所有者或管理员完成设置后,该GitLab会单独列出(在您的GitLab上关联人员账号)。

目标

一个目标指明了CoRoid独立运作的方向、涉及的项目以及可使用的预算。早期版本将目标称为指令;目标对其有完整说明。

目标为CoRoid设定了目标和预算。系统发起的、由目标承接的请求会按照所述流程启动。工作何时启动。CoRoid会在目标下自行处理相关文件,例如某项变更未达到预期效果时的后续处理,这需要对应的有效授权开始工作;在此之前它会等待人工启动。安全相关的修复除外:它们会按照安全模块的设置直接启动。

限额

无论授权如何规定,CoRoid绝对不能自行执行的操作:

  • 受保护路径。这些路径的任何更改都由人工决定。CoRoid会保护登录与访问权限、账单与支付信息、密钥与凭证、加密模块、数据库迁移、锁文件、CI流水线以及容器和基础设施,您也可以自定义新增受保护路径。只有所有者才能移除CoRoid预设的受限路径,且需记录移除原因。
  • 交付操作。授权在此类操作上的最大权限:合并、部署和回滚,每种操作可被允许、请求或拒绝。
  • 开放拉取请求。CoRoid在某个项目中保持开放的自身拉取请求数量。达到限额后,它自行发起的工作会暂停;人工请求的则不受影响。
  • 代理。代理可执行的深度,以及自动化任务和定时任务能否创建新任务。CoRoid审核功能是否阻止pull request,属于授权范畴。

历史记录

指令的所有变更及基于此做出的决策,按时间倒序排列:谁发布或更改了授权,CoRoid被允许或禁止执行哪些操作及原因,以及CoRoid询问时人员的回复内容。

CoRoid向您征求意见时

部分操作需先获得人工答复。每项操作会在下方列为一行需要您处理在Factory中:说明CoRoid要求执行的操作、执行位置和原因。一次性批准允许它执行该操作一次。拒绝则禁止它执行该操作。详见Factory。

谁能修改它

所有者和管理员可以修改指令。所有成员均有权查看完整内容。而 CoRoid 自身的智能体和服务账号则完全无法对其进行更改。

基于授权做出的每一项决策,都会连同该授权及其版本信息一同记录到您组织的审计日志中,这些记录由 CoRoid 生成。