连接 Jira Cloud:分步指南
为每个失败的测试创建一个 Bug,在测试再次失败时添加评论,并在测试完全通过后将其移至已完成状态。本指南将引导你从零开始完成连接并验证,同时列出可能遇到的错误及其原因和解决方法。
最后更新:
请妥善保管您的凭据。切勿将令牌、密钥、密码或 Webhook URL 粘贴到聊天中。请仅在 Studio → 设置 → 集成中输入,凭据会保存到工作区的 .env 文件中,并以圆点显示。对 AI 助手也是如此: 它可以指导您完成本指南中的步骤,但绝不需要您的令牌。
所需准备
- 一个 Jira Cloud 站点,例如 https://your-team.atlassian.net(仅支持 Jira Cloud;地址必须使用 https)。
- 你的 Atlassian 账户邮箱,以及使用同一账户创建的 API 令牌。
- 一个项目键,例如 QA,该项目必须包含名为 Bug 的问题类型。
- 该账户在此项目中拥有浏览、创建问题、添加评论、创建附件和转换问题状态的权限。
获取凭据
- 打开 https://id.atlassian.com/manage-profile/security/api-tokens 并选择创建 API 令牌。
- 为其命名(例如 "Nexus StudioQA"),选择到期时间,创建后立即复制令牌。Atlassian 只会显示一次。
- 将其保留在剪贴板中。除 Studio (下一步) 外,请勿粘贴到任何其他位置。
在 Studio 中连接
- 在 Studio 中,打开设置 → 集成 → 连接 Jira。
- 粘贴 Jira 中的任意链接(首页、看板或问题链接),然后点击检查连接。Studio 会保留站点地址和项目键。
- 出现提示时,输入你的 Atlassian 邮箱和令牌,然后点击保存 & 检查。
- 在 "Bug 归属项目" 中选择项目,然后启用
JIRA_ENABLED。
验证连接是否正常
- 检查连接会显示 "已登录为 <your name>" 和 "<KEY> 接受 Bug 工单"。此检查仅执行读取操作,绝不会创建工单。
- 打开设置 → 集成 → 工单,然后点击创建测试工单。这会创建一个带有 nexus-test 标签的工单,也是该页面上唯一会调用 Jira 的点击操作。
- 在 Jira 中打开该工单,确认它包含 auto-generated、nexus-studioqa-automation 和 nexus-test 标签。完成后将其删除。
常见错误
| 你看到的现象 | 原因 | 解决方法 |
|---|---|---|
| "这不是链接" 或 "Jira 链接以 https:// 开头" | 粘贴的文本不是完整的网址,或以 http:// 开头。 | 访问你的 Jira 站点,复制地址栏中的地址。地址必须以 https:// 开头。 |
| HTTP 401 | 邮箱或令牌有误、令牌已过期或被撤销,或者该邮箱不属于创建令牌的账户。 | 使用你已保存邮箱对应的账户,在 id.atlassian.com 创建新令牌,然后在设置中重新保存邮箱和令牌。 |
| HTTP 403 | 登录成功,但 Jira 提示该账户无权执行此操作:通常是因为缺少项目中的创建问题、添加评论或创建附件权限。 | 请向项目管理员申请这些权限,或选择其他项目。Nexus StudioQA 无法授予这些权限。 |
| HTTP 404 | 站点地址或项目键不存在, 或该账号无权查看此项目 (Jira 会对隐藏的项目返回 404). | 粘贴正确站点中的任意链接, 然后从列表中选择项目. |
| "该地址已响应, 但未返回 Jira 账号" | 该地址不是 Jira Cloud 站点 (例如 Server 或 Data Center 地址, 或其他网页). | 请使用 Jira Cloud 站点的 https://<team>.atlassian.net 地址. |
| "<KEY> 没有名为 Bug 的事项类型" | 该项目没有名为 Bug 的事项类型, 因此无法创建工单. | 在 Jira 中, 打开项目设置 → 事项类型并添加 Bug, 或选择其他项目. |
| "无法连接 Jira (ENOTFOUND)" 或 "未在 20 秒内响应" | 此电脑无法连接站点: 地址拼写错误, VPN 或代理的影响, 或没有网络连接. | 修正地址, 然后在同一台电脑上用浏览器打开站点. 重新检查. |
| 所有检查均通过, 但未出现工单 | JIRA_ENABLED 为 false; 或判定结果为 FLAKY 或环境类判定; 或此次为沙盒运行; 或该测试已有未关闭的 Bug (重复失败时会改为添加评论); 或过去 24 小时内已创建同名 Bug. | 启用 JIRA_ENABLED, 阅读集成页面上的 "每个测试一个事项", 并使用创建测试工单来验证连接. |
| 测试通过后未关闭对应工单 | 工作流中没有与 JIRA_DONE_TRANSITION 同名的转换, 因此只会为工单添加评论. | 将 JIRA_DONE_TRANSITION 设置为工作流中转换按钮的确切名称. |
设置键
| 键 | 功能 | 有效值 | 如何检查 |
|---|---|---|---|
JIRA_ENABLED | 为失败的测试创建 Jira 工单 | true 或 false | 启用集成, 然后运行创建测试工单. |
JIRA_BASE_URL | Jira 站点地址 | https://<site>.atlassian.net | 检查连接会显示站点; 粘贴链接可自动填入站点地址. |
JIRA_EMAIL | Jira 登录邮箱 | 令牌所属 Atlassian 账号的邮箱 | 检查连接会显示 "已登录为 …", 其中包含此邮箱. |
JIRA_API_TOKEN | Jira 访问令牌 (机密, 仅保存在此电脑上) | 单行,不带引号,不含空格 | 检查连接: HTTP 401 表示邮箱与令牌的组合不正确. |
JIRA_PROJECT_KEY | 用于创建 Bug 工单的 Jira 项目 | 项目键, 通常为大写字母, 例如 QA | 项目下拉列表中会列出该项目; "接受 Bug 工单" 表示已确认支持该类型. |
JIRA_DONE_TRANSITION | 测试通过时的 Jira 状态 | 工作流转换的确切名称, 匹配时不区分大小写 | 测试完全通过时会转换工单状态; 如果工作流中没有相应转换, 则只会添加评论. |
更多: 所有集成, 设置指南, 故障排查. 其他指南: Azure Boards, Slack, Microsoft Teams, Telegram, GitHub Issues.
仍然遇到问题?请发送邮件至 [email protected],附上 Studio 显示的完整错误行。请勿包含令牌。