接入研发系统与项目
登记代码平台、需求缺陷系统和流水线,绑定研发项目,按需接收 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,并且这个账号在项目里要有开发者及以上角色。 |
| GitHub | github.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。 |
| Jenkins | CI 流水线 | 任务全名,如 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 |
没有 Webhook 时的行为:已采纳任务的 CI 结果每分钟轮询一次,合并请求的结局每 10 分钟轮询一次,云效的评审人默认每 5 分钟读一次。「指派给我」仍可以由客户端查询得到。