连接 Azure Boards: 分步指南
为每个失败的测试创建一个工作项,在测试再次失败时向该工作项添加评论,并在测试完全通过时将其设为完成状态。同一令牌还可用于发布测试结果和将流水线加入队列。本指南将带您从零开始,完成连接并验证其是否正常,同时列出您可能遇到的错误及其原因和解决方法。
最后更新:
请妥善保管您的凭据。切勿将令牌、密钥、密码或 Webhook URL 粘贴到聊天中。请仅在 Studio → 设置 → 集成中输入,凭据会保存到工作区的 .env 文件中,并以圆点显示。对 AI 助手也是如此: 它可以指导您完成本指南中的步骤,但绝不需要您的令牌。
所需准备
- 一个 Azure DevOps Services 组织: https://dev.azure.com/<organization> 或 https://<organization>.visualstudio.com (不支持部署在您自有计算机上的 Azure DevOps Server)。
- 用于接收工作项的项目名称。
- 具有工作项 → 读取和写入权限的个人访问令牌 (PAT),如果您还使用“在 CI 中运行”,则还需要构建 → 读取和执行权限。
- 了解项目使用的流程,因为它决定了工作项类型: Basic 包含问题、史诗和任务 (不含 Bug); Agile、Scrum 和 CMMI 包含 Bug。
获取凭据
- 打开 dev.azure.com,然后依次选择用户设置 → 个人访问令牌 → 新建令牌。
- 选择您的组织,设置到期时间,并在范围下选择自定义。
- 勾选工作项 → 读取和写入 (如需使用“在 CI 中运行”,还需勾选构建 → 读取和执行),创建令牌并立即复制。令牌只会显示一次。
- 将其保留在剪贴板中。除 Studio (下一步) 外,请勿粘贴到任何其他位置。
在 Studio 中连接
- 在 Studio 中,打开设置 → 集成 → 连接 Azure DevOps。
- 粘贴任意 Azure DevOps 链接 (看板、工作项或项目页面),然后点击检查连接。Studio 会保留组织和项目信息。
- 出现提示时,输入 PAT 并点击保存并检查。在 "工作项目标项目" 中选择项目。
- 如果检查结果提示项目中没有名为 Bug 的工作项类型,请将
AZURE_BOARDS_WORK_ITEM_TYPE设置为列出的类型之一 (Basic 项目中为 Issue),并将AZURE_BOARDS_DONE_STATE设置为该流程中存在的状态 (Basic: Done)。 - 启用
AZURE_BOARDS_ENABLED。
验证连接是否正常
- 检查连接会显示 "令牌可访问 N 个项目" 和 "<project> 接受 <type> 类型的工作项"。检查仅执行读取操作,绝不会创建工作项。
- 打开设置 → 集成 → 工单,然后点击创建测试工单。系统会创建一个带有 nexus-test 标签的工作项,并附上一张截图。
- 在 Azure Boards 中打开该工作项,确认标签和附件,完成后将其删除。
常见错误
| 你看到的现象 | 原因 | 解决方法 |
|---|---|---|
| "Azure DevOps 拒绝了令牌" (HTTP 203 或 401) | PAT 不正确、已过期、已撤销、复制不完整,或是在其他组织中创建的。 | 在 AZURE_DEVOPS_ORG_URL 指定的组织中创建一个具有工作项 → 读取和写入权限的新 PAT,然后重新保存。 |
| HTTP 403 | PAT 有效,但缺少某项权限范围,或您的用户在该项目中没有相应权限。 | 编辑 PAT 的权限范围 (工作项 → 读取和写入; 如需使用“在 CI 中运行”,还需构建 → 读取和执行),或向项目管理员申请访问权限。 |
| HTTP 404 | 组织或项目名称不存在,或项目已重命名。 | 粘贴正确项目中的链接,然后从列表中选择该项目。 |
| VS402323 "工作项类型 Bug 不存在" | 项目流程中没有该名称的工作项类型。Basic 项目包含问题、史诗和任务,不包含 Bug。 | 将 AZURE_BOARDS_WORK_ITEM_TYPE 设置为检查结果中列出的类型 (Basic: Issue),并将 AZURE_BOARDS_DONE_STATE 设置为其中一种状态 (Basic: Done),然后再次点击检查连接。 |
| "<project> 中没有名为 … 的工作项类型" | 原因与 VS402323 相同,由检查连接在提交任何工作项之前检测到。 | 将 AZURE_BOARDS_WORK_ITEM_TYPE 设置为该消息中列出的类型之一,或选择其他项目。 |
| "这不是 Azure DevOps 链接" | 地址不属于 dev.azure.com/<organization> 或 <organization>.visualstudio.com,或者以 http:// 开头。 | 从 Azure DevOps Services 的浏览器地址栏复制地址。不支持 Azure DevOps Server。 |
| "无法连接到 Azure DevOps (…)" 或 "未在 20 秒内响应" | 此电脑无法连接到 Azure DevOps: 可能是 VPN 或代理所致,也可能没有网络连接。 | 在同一台电脑的浏览器中打开 dev.azure.com,然后重试检查。 |
| 测试通过后未设置为完成状态 | 流程不允许为该类型设置 AZURE_BOARDS_DONE_STATE 指定的状态,因此只会向工作项添加评论。 | 将 AZURE_BOARDS_DONE_STATE 设置为该类型的某个状态 (Basic: Done; Agile 缺陷: Resolved)。 |
| 所有检查均正常,但没有出现工作项 | AZURE_BOARDS_ENABLED 为 false; 或判定结果为 FLAKY 或环境问题; 或此次为沙盒运行; 或该测试已有未关闭的工作项 (重复失败时会改为添加评论)。 | 启用 AZURE_BOARDS_ENABLED,并使用创建测试工单来验证连接。 |
设置键
| 键 | 功能 | 有效值 | 如何检查 |
|---|---|---|---|
AZURE_BOARDS_ENABLED | 为失败创建 Azure 工作项 | true 或 false | 检查连接通过后启用,然后运行创建测试工单。 |
AZURE_DEVOPS_ORG_URL | Azure DevOps 组织地址 | https://dev.azure.com/<organization> 或 https://<organization>.visualstudio.com | 检查连接会显示组织; 粘贴链接会自动填入该字段。 |
AZURE_DEVOPS_PROJECT | Azure DevOps 项目名称 | 项目名称,必须与 Azure DevOps 中显示的完全一致 | 检查连接会列出令牌可访问的项目。 |
AZURE_DEVOPS_PAT | Azure DevOps 访问令牌 (机密,仅保存在此电脑上) | 单行,不带引号,不含空格 | 检查连接: "令牌被拒绝" 表示令牌错误、已过期或来自其他组织。 |
AZURE_BOARDS_WORK_ITEM_TYPE | 用于失败的 Azure 工单类型 | 项目流程中存在的类型: Bug (Agile, Scrum, CMMI) 或 Issue (Basic) | 检查连接会显示 "<project> 接受 <type> 类型的工作项",或列出项目已有的类型。 |
AZURE_BOARDS_DONE_STATE | 测试通过时的 Azure 状态 | 该工作项类型的某个状态: Resolved (Agile 缺陷), Done (Basic 问题) | 测试一次通过时会更改工作项状态; 如果流程不允许该状态,则只会添加评论。 |
AZURE_PIPELINE_ID | 在 CI 中运行的 Azure 流水线 | Azure 流水线的数字 ID (仅用于在 CI 中运行) | nexus ci-remote --provider=azure 会将该流水线加入队列; 需要生成 → 读取 & 执行权限。 |
更多: 所有集成, 设置指南, 故障排查. 其他指南: Jira Cloud, Slack, Microsoft Teams, Telegram, GitHub Issues.
仍然遇到问题?请发送邮件至 [email protected],附上 Studio 显示的完整错误行。请勿包含令牌。