研枢:研发交付

接入研发系统与项目

登记代码平台、需求缺陷系统和流水线,绑定研发项目,按需接收 Webhook。

接入研发系统

打开「研发(研枢) › 研发系统连接」,点右上方的「新增连接」,侧栏标题是「新增研发系统连接」。研发系统连接最多 100 个。列表可以按名称、地址或服务账号搜索,也可以按系统类型和状态筛选。每个连接显示三个相互独立的状态:「启用」或「已停用」,凭据是否「已加密保存」及更新时间,以及最近一次测试的结果。没有在本页测试过的连接显示「未测试」。

字段含义
连接名称必填,最多 100 个字符,例如「公司 GitLab」。
系统类型GitLab、GitHub、Gitee、禅道、Jenkins、云效。保存后不能更换。
服务地址必填,以 http:// 或 https:// 开头。各系统的写法见下表。
组织 ID只有云效有。中心版必填。
服务账号只有禅道和 Jenkins 有,因为它们用账号加密码或令牌登录。其他系统的令牌自己代表一个用户。
凭据字段名随系统类型变化(访问令牌、密码、API Token、个人访问令牌、私人令牌)。新建时必填,加密保存,只写不回显。
外部 ID 体系编码(可选)默认等于系统类型。同一个部署里有两套同类系统时,给其中一套另填编码,例如 gitlab_cn,并在人员目录里按这个编码登记账号。编码以小写字母开头,只含小写字母、数字和下划线,最长 32 个字符。
说明(可选)最多 500 个字符,例如服务账号的权限范围和负责人。
定时检查合并请求的评审人只有云效有,默认勾选。Codeup 给已有合并请求加评审人时不发 Webhook,勾选后研枢默认每 5 分钟读一次打开的合并请求,给新评审人提示「请我评审」,检查周期可由部署配置调整或关闭。每个连接至多检查 50 个代码仓库。
启用停用的连接不再用于读取研发数据。
研枢新增研发系统连接侧栏
「研发(研枢) › 研发系统连接」里的「新增研发系统连接」侧栏。截图来自测试环境,数据为示例。

各系统要填什么

系统服务地址凭据与权限
GitLab例如 https://git.example.com。部署在子路径下时带上子路径。服务账号的个人、项目或群组访问令牌,读数据只需要 read_api。采纳结果要创建合并请求,另需 api,并且这个账号在项目里要有开发者及以上角色。
GitHubgithub.com 填 https://api.github.com。GitHub Enterprise Server 填 https://<主机>/api/v3。GHE.com 填 https://api.<子域名>.ghe.com。个人访问令牌,代表创建它的用户。Fine-grained 令牌选好要绑定的仓库,Metadata、Contents、Actions、Checks 至少只读。采纳时要建拉取请求、评论或关闭议题,Pull requests 和 Issues 选读写。Classic 令牌勾选 repo 与 workflow。令牌用户须能访问仓库,否则 GitHub 答 404。
Gitee填 https://gitee.com/api/v5。填网页地址 https://gitee.com 会被拒绝。私人令牌,代表生成它的用户。勾选 user_info、projects、pull_requests、issues、notes。令牌权限范围不含某个仓库时,Gitee 对它答 404。
禅道例如 https://zentao.example.com。部署在子路径下时带上子路径。填服务账号,凭据填它的密码,用于换取禅道的接口令牌。账号要能查看所绑定产品的需求、缺陷和迭代。采纳时要在需求、缺陷上评论或改状态,另需相应权限。
Jenkins例如 https://jenkins.example.com。部署在子路径下时带上子路径。填服务账号,凭据填它在 Jenkins「用户 › 设置 › API Token」里生成的令牌。账号只需要能查看所绑定的任务。
云效中心版填 https://openapi-rdc.aliyuncs.com,同时填组织 ID。Region 版填组织专属域名,不填组织 ID。个人访问令牌,以 pt- 开头,在云效头像菜单的「个人设置 › 个人访问令牌」里创建。代码管理、项目协作、流水线三项至少只读,采纳要创建合并请求、评论或改工作项状态时选读写。令牌用户还要是要绑定的代码库、Projex 项目和 Flow 流水线的成员,否则云效答 403。

一个云效连接同时提供 Codeup、Projex 和 Flow 三类能力,绑定研发项目时分别选仓库、项目空间和流水线。组织 ID 取自 Codeup 代码库地址 codeup.aliyun.com/<组织 ID>/仓库名 的第一段,或云效「组织管理 › 基本信息」。

保存、测试、停用

  • 点「保存连接」。保存后页面提示下一步:先「测试连接」,再到「研发项目」绑定。
  • 「测试连接」只读取,不会写入研发系统。通过时显示系统版本、服务账号和用时。没通过时显示原因,可以直接点「编辑连接」。
  • 凭据只写不回显。编辑时留空表示保持原凭据,填写表示轮换,旁边的标记会显示「将轮换」。修改服务地址、服务账号或组织 ID 时,必须重新填写凭据。
  • 停用在更多操作里,会先确认。停用后,绑定了这个连接的研发项目暂时读不到该系统的数据。
  • 两个人同时编辑同一个连接时,后保存的会看到「版本冲突,没有保存」,需要重新打开最新版本再改。
研枢访问研发系统走出站网络,并受出站白名单限制。研发系统在内网时,需要运维把它的地址加入部署配置里的 ECHOMIND_EGRESS_ALLOW,否则测试连接会提示出站策略拒绝了该地址。GitHub 拉取 Actions 作业日志时会跳转到存储主机(productionresultssa*.blob.core.windows.net、*.actions.githubusercontent.com),白名单也要放行。GitHub Enterprise Server 的存储主机由运维另行配置。

绑定研发项目

打开「研发(研枢) › 研发项目」,点「新建研发项目」。研发项目最多 2000 个。列表显示每个项目绑定的代码仓库、需求与缺陷和 CI 流水线,范围可以在「进行中」和「已归档」之间切换。

字段含义
项目名称必填,最多 100 个字符,例如「支付中心」。
项目编码必填。小写字母开头,2 到 48 个字符,只含小写字母、数字和连字符,例如 pay-center。创建后不能修改,授权以编码记录。包含已归档项目在内,编码都不能重复。
说明(可选)最多 1000 个字符。
代码仓库最多 20 项。每一行选一个连接,再填仓库路径。
需求与缺陷最多 5 项。
CI 流水线最多 20 项。
相关文档最多 20 项。从已安装的文档检索模块(例如知汇)里挑选资源。绑定后,AI 工具用 docs_search 只在这些文档里检索,并且仍受调用者在文档模块里授权的限制。没有这样的模块时,这一块会提示暂不能选择。

每个绑定行只能选类型匹配的连接:

系统可以绑定为路径或编号怎么写
GitLab代码仓库、需求与缺陷(GitLab Issues)、CI 流水线(GitLab CI)项目路径,如 group/subgroup/project。
GitHub代码仓库、需求与缺陷(Issues 和里程碑)、CI 流水线(Actions 运行)三处都写同一个 owner/repo,取自仓库网址 github.com/ 之后的两段。类型、优先级、严重度取自标签,如 bug、enhancement、priority: high。
Gitee代码仓库、需求与缺陷(Issues 和里程碑)owner/repo。Gitee 不开放 Gitee Go 流水线的接口,不能用于 CI 流水线,请用 Jenkins 等其他连接。
禅道需求与缺陷产品 ID,如 12。迭代按项目的执行统计时写成 产品 ID@项目 ID,如 12@7。
JenkinsCI 流水线任务全名,如 folder/job。
云效代码仓库(Codeup)、需求与缺陷(Projex)、CI 流水线(Flow)Codeup 写仓库路径 namespace/repo,含代码组时 group/subgroup/repo。Projex 写项目空间 ID,取自地址 devops.aliyun.com/projex/project/<ID>/,注意不是 NXACC 这样的项目编号。Flow 写流水线 ID,取自地址 flow.aliyun.com/pipelines/<ID>/ 中的数字。
研枢新建研发项目侧栏
「研发(研枢) › 研发项目」里的「新建研发项目」侧栏。截图来自测试环境,数据为示例。

还没有任何连接时,编辑页会提示先去新增连接。点「前往新增连接」不会丢掉已经填的内容,新增并测试连接后回来继续。你也可以先保存项目,以后再绑定。保存成功后,页面提示下一步是到「授权管理」授权。

项目可以「归档」,在更多操作里。归档后授权保留,但 Agent 看不到这个项目,也不能修改它。在「已归档」范围里可以恢复。

接收 Webhook(可选)

Webhook 有两个用途:把合并请求的 CI 结果补充到任务里,以及给开发者提示可以交给 AI 的事项,包括「流水线失败」「任务的 CI 失败」「指派给我」「请我评审」和「可以整理注意事项」。提示保留 14 天,从不自动发起任务。

配置方法:打开「接入中心 › 入站事件」,在「事件来源」里登记来源,接收模块选研枢,认证方式选对应的系统,控制台会预填它处理的事件类型。Nexus 生成的令牌只显示一次。然后在研发系统里填推送地址 /v1/events/<来源编码> 和令牌。

系统在研发系统里的位置要勾选的事件
GitLab项目或群组「设置 › Webhooks」,Secret token 填 Nexus 生成的值流水线、合并请求、议题事件
Jenkins任务的「Job Notifications」,需要装 Notification 插件,地址写成 https://nexus:<令牌>@<Nexus 地址>/v1/events/<来源编码>Event 选「Job completed」,Format 选 JSON,Branch 保持 .*(为空不发通知)
禅道「后台 › 二次开发 › Webhook」,类型选「其他」,地址带 ?token=<令牌>参数至少勾选对象类型、对象 ID、所属产品、动作、操作者
云效 Codeup仓库「设置 › Webhooks」,密钥令牌填 Nexus 生成的值合并请求事件
云效 Flow流水线里给任务添加「Webhook 通知」插件,地址带 ?token=<令牌>在同一个插件里勾选「失败」和「成功」,插件放在最后一个任务上
云效 Projex项目「设置 › 自动化规则」,从「Webhook 集成」里选模板「当 工作项 的 字段 变更 时,触发 Webhook」,Secret 填 Nexus 生成的值,地址不能带查询字符串。自动化规则是云效 Projex 的专业版功能字段选「负责人」,HTTP method 选 POST,Webhook body 选「工作项数据」
GitHub仓库或组织「Settings › Webhooks」,Content type 选 application/json,Secret 填 Nexus 生成的值Workflow runs、Pull requests、Issues
Gitee仓库「管理 › WebHooks」,把 Nexus 生成的值填在密码或签名密钥里Pull Request、Issues
GitHub 对每次请求体都签名,GitLab 19.0 及以上和 Gitee 可选签名方式,其余系统只能携带明文令牌(Gitee 的签名也不覆盖请求体)。请只用 HTTPS 推送,并定期更换令牌。github.com、gitee.com 和云效发不到内网地址,Nexus 部署在内网时,需要有公网可达的入口。不接受这些限制时,可以不配置 Webhook,研枢会改为轮询。

没有 Webhook 时的行为:已采纳任务的 CI 结果每分钟轮询一次,合并请求的结局每 10 分钟轮询一次,云效的评审人默认每 5 分钟读一次。「指派给我」仍可以由客户端查询得到。

进一步交流

带一件正在做的事来聊

告诉我们你想让智能体接哪一类系统。我们在演示环境里把这件事走一遍,再一起判断合不合适。