Jira Cloud 集成

用于问题跟踪、冲刺管理和工作日志操作的 Jira Cloud REST API 集成。

身份验证

Jira Cloud 使用 API 令牌进行身份验证。所需的环境变量：

• - JIRABASEURL - 您的 Jira 实例（例如 https://yourcompany.atlassian.net）
• JIRAUSEREMAIL - Atlassian 账户邮箱
• JIRAAPITOKEN - 来自 https://id.atlassian.com/manage-profile/security/api-tokens 的 API 令牌

测试连接：
bash
curl -s -u $JIRAUSEREMAIL:$JIRAAPITOKEN $JIRABASEURL/rest/api/3/myself | jq .

快速参考

所有操作均使用 scripts/jira.py 脚本：

操作	命令
搜索 (JQL)	jira.py search project = PROJ AND status = Open
查看问题

jira.py get PROJ-123 |
| 创建问题 | jira.py create PROJ --type Task --summary 标题 --description 正文 |
| 更新问题 | jira.py update PROJ-123 --summary 新标题 |
| 添加评论 | jira.py comment PROJ-123 评论内容 |
| 状态转换 | jira.py transition PROJ-123 进行中 |
| 列出看板 | jira.py boards |
| 获取冲刺 | jira.py sprints BOARD_ID |
| 冲刺问题 | jira.py sprint-issues SPRINT_ID |
| 记录工时 | jira.py worklog PROJ-123 --time 2h 30m --comment 完成的工作 |
| 获取工作日志 | jira.py worklogs PROJ-123 |

常见工作流程

搜索问题

JQL（Jira 查询语言）支持强大的过滤功能：

bash

分配给我的未关闭问题

jira.py search assignee = currentUser() AND status != Done

本周更新过的问题

jira.py search project = PROJ AND updated >= startOfWeek()

高优先级缺陷

jira.py search type = Bug AND priority in (High, Highest)

当前冲刺中的问题

jira.py search sprint in openSprints() AND project = PROJ

输出：包含问题键、摘要、状态、经办人、优先级的 JSON 数组。

创建问题

bash

基本任务

jira.py create PROJ --type Task --summary 实现功能 X

带描述和优先级的缺陷

jira.py create PROJ --type Bug \ --summary 移动端登录失败 \ --description 复现步骤：1. 打开应用 2. 输入凭据 \ --priority High

带标签和组件的用户故事

jira.py create PROJ --type Story \ --summary 用户个人资料页面 \ --labels frontend,ui \ --components Web App

更新问题

bash

更新摘要

jira.py update PROJ-123 --summary 更新后的标题

更新多个字段

jira.py update PROJ-123 \ --description 新描述 \ --priority Medium \ --labels backend,api

分配给用户

jira.py update PROJ-123 --assignee user@company.com

状态转换

转换取决于工作流配置。首先获取可用的转换：

bash

列出可用的转换

jira.py transitions PROJ-123

移动到某个状态

jira.py transition PROJ-123 进行中 jira.py transition PROJ-123 完成

冲刺管理

bash

列出所有看板

jira.py boards

获取某个看板的冲刺

jira.py sprints 42

获取活跃冲刺的问题

jira.py sprint-issues 100

过滤：仅活跃冲刺

jira.py sprints 42 --state active

工作日志记录

bash

记录花费的时间

jira.py worklog PROJ-123 --time 1h 30m --comment 代码审查

记录指定日期

jira.py worklog PROJ-123 --time 4h --started 2024-03-14T09:00:00.000+0000

查看现有工作日志

jira.py worklogs PROJ-123

字段参考

参见 references/fields.md 了解：

• - 标准字段名称和 ID
• 自定义字段处理
• 用于富文本的 ADF（Atlassian 文档格式）

错误处理

常见错误：

• - 401 未授权：检查 JIRAUSEREMAIL 和 JIRAAPITOKEN
• 404 未找到：问题键或项目不存在
• 400 错误请求：字段值无效或缺少必填字段

原始 API 访问

对于脚本未覆盖的操作：

bash

GET 请求

curl -s -u $JIRAUSEREMAIL:$JIRAAPITOKEN \
$JIRABASEURL/rest/api/3/issue/PROJ-123 | jq .

POST 请求

curl -s -X POST -u $JIRAUSEREMAIL:$JIRAAPITOKEN \ -H Content-Type: application/json \ -d {body: {type: doc, version: 1, content: [{type: paragraph, content: [{type: text, text: 评论}]}]}} \ $JIRABASEURL/rest/api/3/issue/PROJ-123/comment | jq .

API 文档：https://developer.atlassian.com/cloud/jira/platform/rest/v3/