jira

jira — 在终端中使用 Jira Issue Tracker

通过 REST API v3 与 Atlassian Jira Cloud 交互。搜索问题、查看详情、创建问题、添加评论、统计匹配数、列出项目并转换状态。

设置

1. 在 id.atlassian.com/manage/api-tokens 生成 API 令牌
2. 设置环境变量：

export JIRA_EMAIL="[email protected]"       # Atlassian account email
export JIRA_API_TOKEN="YOUR_API_TOKEN"           # from id.atlassian.com
export JIRA_SERVER="https://your-domain.atlassian.net"

身份验证采用 HTTP Basic，凭据格式为 base64(email:token)——使用你的电子邮件地址，绝不能使用密码（密码已不再用于 API）。Cloud 不提供 Personal Access Tokens；Bearer PAT 仅适用于 Data Center。令牌现在最长一年后过期。--help 和 --dry-run 无需凭据即可使用。

基本命令

me / projects — 身份和范围

jira me                       # verify auth; your accountId, timezone
jira projects --json          # all accessible projects

list — 搜索问题

jira list                                                # recent issues
jira list --project PROJ                                 # by project
jira list --jql 'assignee=currentuser() AND status=Open' # custom JQL
jira list --project PROJ --max 120 --json                # >50 auto-pages via startAt offsets

view — 问题详情

jira view PROJ-123                        # summary, status, assignee, description
jira view PROJ-123 --json                 # machine-readable

描述以 Atlassian Document Format（ADF）格式返回；CLI 会提取纯文本以供显示。

count — 快速统计匹配总数

jira count --jql 'issuetype = Bug AND resolution = Unresolved'   # {"count": N}

使用 POST /search/approximate-count，不获取记录。JQL 本身没有 COUNT/聚合功能。

create — 创建问题

jira --yes create --project PROJ --summary "Fix login bug"            # Task (default)
jira --yes create --project PROJ --summary "Crash on startup" --type Bug
jira --yes create --project PROJ --summary "Add dark mode" --type Story --priority High
jira create --project PROJ --summary "Test" --dry-run           # preview payload

描述以 ADF 文档形式发送。纯段落之外的富文本格式需要原始 ADF JSON——请参阅 references/rest-issues-and-transitions.md。

comment — 添加评论

jira --yes comment PROJ-123 -m "Fixed in latest build"
jira comment PROJ-123 -m "Looking into it" --dry-run

transitions + transition — 状态变更

jira transitions PROJ-123                     # LIST valid transition IDs first
jira --yes transition PROJ-123 --to "In Progress"   # then apply by name or ID
jira --yes transition PROJ-123 --to Done --resolution Done
jira transition PROJ-123 --to "In Review" --dry-run

不确定时，请始终先运行 transitions：ID 因工作流和当前状态而异，而且不同工作流中的名称可能重复。--resolution 可满足 Done 类屏幕的必填要求；省略它会返回 400，并在错误中指出缺少的字段。

全局标志

所有标志均可放在任意位置。读取命令需要凭据；--help 和 --dry-run 不需要。修改命令必须显式通过 --yes/--force 确认：

jira --json list --project PROJ                        # machine output anywhere
jira --dry-run create --project PROJ --summary "Test"  # offline preview
jira --yes create --project PROJ --summary "Test"      # explicit write authorization
jira --quiet list                                      # suppress non-essential output

--json 会在 stdout 上为每条命令输出一个 JSON 对象——可通过管道传给 jq 处理结构化数据。

多步骤流水线示例

Sprint 健康状况检查

找出 Sprint 中停滞的工作，逐项查看工单，并关闭已完成的工单：

jira list --jql 'sprint IN openSprints() AND updated < -14d AND resolution = Unresolved' --json \
  | jq -r '.issues[].key' \
  | while read -r key; do jira view "$key"; jira transitions "$key"; done
# after human review, per key:
jira --yes transition "$key" --to Done --resolution Done

list --json 的数据结构为 {"total": N, "issues": [{"key", "summary", "status", "assignee", "issuetype", "priority"}]}。

安全发现后批量关闭

转换 ID 因工作流而异——写入前先查询：

for key in $(jira list --jql 'status = "In Progress" AND updated < -30d' --json | jq -r '.issues[].key'); do
  tid=$(jira transitions "$key" --json | jq -r '.transitions[] | select(.status_category=="completed") | .id' | head -1)
  [ -n "$tid" ] && jira --yes transition "$key" --to "$tid" --resolution Done
done

使用 jq 生成每周摘要

jira list --jql 'assignee = currentUser() AND updated >= startOfWeek()' --max 50 --json \
  | jq -r '.issues[] | "\(.key)\t\(.status)\t\(.summary)"'

更多可直接运行的查询见 references/jql-cookbook.md，其中按角色进行了分类。

使用 --json 和 jq

jira list --project PROJ --json | jq '.issues[] | {key, status, assignee}'
jira count --jql 'project = PROJ' --json | jq .count
jira transitions PROJ-123 --json | jq -r '.transitions[] | "\(.id)=\(.name) -> \(.to_status)"'

已知注意事项

• 搜索端点存在两种形式 — 此 CLI 使用经典的 /rest/api/3/search，采用偏移量分页（startAt、maxResults、total）。Atlassian 的增强版 /rest/api/3/search/jql 用不透明的 nextPageToken（以及 isLast）取代了它，不再有 startAt 和 total，默认只返回 ID 字段，而且会拒绝无界 JQL（单独使用 order by key desc → 400）。经典端点已弃用（“目前正在移除”，于 2024 年 10 月公布，并承诺在 2025 年 5 月 1 日之后移除），因此请做好被迫迁移的准备；混用这两种分页模式是导致无限循环停留在第一页的典型原因。
• 分页上限 — 旧版页面默认 maxResults=50；total 可能在翻页期间缩小，因此应始终能处理空页面，不要依赖过时的总数。
• 转换前需要先 GET — 转换 ID（"31"、"711"）仅适用于某个工作流／状态；请求无效 ID 会返回空列表，而非错误。“已完成”类型的界面通常要求提供 resolution；缺少必填字段时会返回 400，并通过 "errors": {"resolution": "..."} 指出这些字段。
• 到处都是 ADF — v3 请求负载中的描述、评论和环境字段都需要 ADF JSON 对象；直接传入字符串会被拒绝。
• 身份验证 使用 HTTP Basic，以及电子邮件地址和 API 令牌。CAPTCHA 锁定（多次登录失败）会完全阻止 REST 身份验证；症状是响应头：X-Seraph-LoginReason: AUTHENTICATION_DENIED。请在浏览器中解决，不要反复重试。
• 速率限制 会返回 429，并附带 Retry-After 和 RateLimit-Reason 响应头；CLI 会显示这两个响应头，但不会自动重试。写入操作对每个问题还限制在约 2 秒 20 次。
• 项目键在某些场景下区分大小写，不过 API 通常接受任意大小写。
• 使用 accountId，而非 username — 用户字段接受 Atlassian 账户 ID（GDPR 迁移所致）；API 已移除用户名。

JQL 注意事项

• != 会排除空值 — assignee != currentUser() 会静默排除未分配的问题。应写为 (assignee != currentUser() OR assignee IS EMPTY)。
• AND 的优先级高于 OR — A OR B AND C 会解析为 A OR (B AND C)。OR 分组务必加括号；不加括号时会从左到右求值。
• 不支持前置通配符 — summary ~ "*bug" 会强制执行全量扫描；请将通配符放在开头字符之后。
• 优先按项目筛选 — 这是大型实例中最有效的性能优化手段（官方优化指南）。
• 历史运算符有字段白名单 — WAS／CHANGED 仅适用于 Assignee、Fix Version、Priority、Reporter、Resolution 和 Status；用于没有历史记录的字段时会静默返回空结果。
• 相对日期区分大小写 — -1m 表示分钟，-1M 表示月份；按天计算的表达式会根据每位用户的时区进行计算。
• JQL 不支持聚合 — 没有 COUNT／SUM；请使用 jira count（近似计数端点）或仪表板小程序。

适用场景

• 在终端中进行任何 Jira Cloud 交互：搜索、查看、创建、评论、转换
• 编写、调试或优化 JQL 查询 — 内含完整的语言参考
• Sprint 评审、分类筛查、批量状态维护、仪表板和已保存筛选器设计

不适用场景

不要将此技能用于 GitHub 或 GitLab 问题跟踪（请使用这些平台自己的工具，例如 gh）、Jira 站点管理（如权限方案或工作流编辑，这些应在管理界面中完成）、Confluence 内容，或针对 Jira API 构建服务器端集成（请改用 Atlassian 官方 SDK 文档）。

参考文件

文件	主题	适合阅读的场景
references/rest-auth-and-search.md	基本身份验证／令牌机制与 OAuth／PAT、速率限制响应头、错误封装、旧版与增强版搜索的分页差异	设置凭据、处理 429／401 错误、对大型搜索结果分页，或从 /search 迁移
references/rest-issues-and-transitions.md	GET／POST／PUT 问题数据结构、包含屏幕字段要求的 transitions GET→POST 流程、ADF 文档模型	以编程方式创建／编辑问题、解决状态转换失败，或设置富文本格式
references/jql-functions-catalog.md	所有 JQL 函数及其支持的字段／运算符——日期／时间、用户、冲刺／版本、自定义字段、JSM 审批与 SLA	检查查询可以使用哪些运算符／函数
references/jql-best-practices.md	运算符优先级、性能规则、空值陷阱、故障排查流程、Marketplace 扩展	查询速度慢、结果错误，或混用了 AND／OR
references/jql-cookbook.md	按角色整理的 50 条可直接运行的查询（开发者、Scrum Master、PO／经理、高级用户、管理员）	创建筛选器、自动化规则，或进行冲刺评审
references/jql-history-and-dates.md	WAS／CHANGED 谓词详解、相对日期表达式表、已保存筛选器的组合与命名约定	编写历史查询、计算日期，或设计可复用的已保存筛选器

可用脚本

脚本	用途	调用方式
scripts/jira	此技能调用的 CLI：me、list、view、projects、create、comment、count、transitions、transition——均支持 --json／--dry-run、延迟身份验证、超过 50 条结果时使用偏移分页获取、解析后的 API 错误消息，以及显示 429 Retry-After。处理上述任何 Jira 数据问题时都应运行它。	scripts/jira list --project PROJ --json
scripts/test_jira.py	离线 pytest／unittest 套件，涵盖帮助文本、参数错误、dry-run 计划、分页循环、错误封装及状态转换解析逻辑——不进行网络请求。修改 scripts/jira 后运行。	.venv/bin/python3 -m pytest -p no:cacheprovider --strict-markers scripts/test_jira.py

先决条件

• Python 3.8+ 和 requests（否则使用标准库）；如果无法直接执行，请使用 python3 scripts/jira ... 调用
• 任何非 dry-run 命令都需要导出 JIRA_EMAIL + JIRA_API_TOKEN（令牌获取地址：https://id.atlassian.com/manage/api-tokens）；`JIRA_SERVER` 默认值为 https://your-domain.atlassian.net
• 建议安装 jq，用于对 --json 输出进行后处理

限制

• 面向 Jira Cloud REST v3；Data Center 站点使用不同的身份验证方式（Bearer PAT），并提供较旧的 API
• 此 CLI 使用的经典搜索端点已被上游弃用；预计最终会被强制迁移到采用令牌分页的 /search/jql
• 除纯段落外，创建富文本需要手动构建 ADF JSON
• 429 错误不会自动重试；连续执行多次写入的循环应在调用之间休眠