jira

使用 orbit CLI 管理 Jira

使用 orbit CLI 管理 Jira 议题、史诗、冲刺、看板、项目、版本、自定义字段、屏幕、状态和议题类型。支持 Jira Cloud（REST API v3）以及 Jira Server/Data Center（REST API v2），并支持多配置文件和 1Password 密钥解析。

前提条件

1. 已安装 orbit CLI——如果 which orbit 执行失败，请使用以下方式安装：
   • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
   • macOS/Linux（脚本）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
   • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
2. ~/.config/orbit/config.yaml 中配置了 jira-cloud 或 jira-onprem 服务的配置文件
3. 有效凭据——Cloud 使用 API 令牌（通过电子邮件地址 + 令牌进行基本身份验证），Server 使用 PAT
4. 凭据可存储为 1Password（op://）或 Infisical（infisical://）引用，以便自动解析

快速参考

所有命令都遵循以下格式：orbit -p <profile> jira <resource> <action> [flags]

命令树到此为止——<action> 始终是叶节点，因此没有 <action> list。读取操作和写入操作使用不同的操作名称：issue view --comments 用于读取评论，issue comment 仅用于写入评论；issue attachments 用于列出附件，issue attach 仅用于上传。猜测子命令并非只是容易出错，而是不安全：写入操作将议题键作为第一个位置参数，因此 jira issue comment list PROJ-123 会被解析为议题键 list、正文 PROJ-123，并作为实际写入操作发送到 Jira。请查看 references/commands.md，不要猜测。

-o 标志用于控制输出格式：table（默认）、json、yaml。

完整的命令详情和标志请参阅 references/commands.md。 Jira wiki 标记语法格式请参阅 references/wiki-markup.md（仅适用于 Server）。

核心工作流

查看议题

# View issue with comments (shows last 10 by default)
orbit -p myprofile jira issue view PROJ-123

# View with more comments
orbit -p myprofile jira issue view PROJ-123 --comments 50

# JSON output (includes full data + all comments)
orbit -p myprofile jira issue view PROJ-123 -o json

view 命令会显示：摘要、类型、状态、优先级、经办人、报告人、标签、组件、描述、子任务、链接、附件（包括文件名、大小、下载 URL），以及评论的作者、日期和编辑时间戳。附件会显示在评论之前，以便查看评论文本中引用的屏幕截图时了解其上下文。

创建议题

# Simple story
orbit -p myprofile jira issue create --project PROJ --type Story --summary "Add login page"

# Bug with priority and assignment
orbit -p myprofile jira issue create --project PROJ --type Bug \
  --summary "Fix timeout" --priority High --assignee john.doe

# Sub-task under a parent
orbit -p myprofile jira issue create --project PROJ --type Sub-task \
  --parent PROJ-123 --summary "Add validation"

创建史诗

史诗需要设置“Epic Name”自定义字段。使用 --type Epic 时，orbit CLI 会自动将摘要设为该字段的值。使用 --epic-name 可覆盖此值。

# Create an epic (Epic Name auto-set from summary)
orbit -p myprofile jira issue create --type Epic --project PROJ \
  --summary "Q1 Auth Revamp" --priority Highest

# Create epic with Parent Link to a Capability/Initiative
orbit -p myprofile jira issue create --type Epic --project PROJ \
  --summary "Okta Authentication Foundation" \
  --field "customfield_27521=PRT-4378" \
  --priority Highest

--field 标志可通过 key=value 设置任意自定义字段。使用 jira field list 查找字段 ID。

使用格式化描述编辑议题

Jira Server 使用 wiki 标记语法，而非 Markdown。Jira Cloud 使用 ADF（orbit 会自动处理纯文本）。对于 Server 实例，--body 的值始终应使用 wiki 标记语法进行格式化。

orbit -p myprofile jira issue edit PRT-123 --body "h2. Value Statement

The platform provides real authentication via Okta.

h2. User Stories

* *Story 1:* As a platform admin, I want all API requests to require a valid Okta JWT.
** Okta custom AS configured with epsilon_claims claim
** AUTH_BYPASS removed from all Terraform task definitions"

编辑自定义字段值

-F 标志支持多种值格式。正确的格式取决于 Jira 字段类型：

# Single-select field — use value: shorthand
orbit -p myprofile jira issue edit PROJ-123 -F customfield_10397=value:Yes

# Multi-select field — MUST use JSON array of objects (value: shorthand will return 400)
orbit -p myprofile jira issue edit PROJ-123 -F 'customfield_10398=[{"value":"Developer"},{"value":"QA"}]'

# Multi-select with a single value still needs array format
orbit -p myprofile jira issue edit PROJ-123 -F 'customfield_10400=[{"value":"Confirmed"}]'

# Number field
orbit -p myprofile jira issue edit PROJ-123 -F customfield_10399=3

# Plain string field
orbit -p myprofile jira issue edit PROJ-123 -F customfield_10010=my-value

重要： 多选字段（复选框、多选下拉框）必须使用 [{"value":"X"}] 数组格式。在多选字段上使用 value:X 会返回 400 错误。

转换议题状态

# Move to In Progress
orbit -p myprofile jira issue move PROJ-123 "In Progress"

# Close with comment and resolution
orbit -p myprofile jira issue move PROJ-123 Done --comment "Fixed in v2.1" --resolution Fixed

使用 @mentions 添加评论

issue comment 用于写入评论。要读取评论，请使用 issue view --comments N（参见查看议题）。

在评论中使用 [~accountId:ID] @提及用户（Cloud）。Jira 会将其显示为可点击的用户链接。对于 Server，请使用 [~username]。

# Add a comment mentioning the assignee
orbit -p myprofile jira issue comment PROJ-123 -b "Hey [~accountId:5b10ac8d82e05b22cc7d4ef5], this needs rework"

# Look up a user's accountId
orbit -p myprofile jira user search "Jorge"

附件

# Attach a file to an issue
orbit -p myprofile jira issue attach PROJ-123 report.pdf

# Attach multiple files
orbit -p myprofile jira issue attach PROJ-123 screenshot.png log.txt

# List attachments
orbit -p myprofile jira issue attachments PROJ-123

# Download all attachments
orbit -p myprofile jira issue download PROJ-123

# Download only screenshots/images
orbit -p myprofile jira issue download PROJ-123 --images-only --output ./screenshots

# Remove an attachment by ID
orbit -p myprofile jira issue detach 12345

搜索问题

# Filter by project and type
orbit -p myprofile jira issue list --project PROJ --type Epic

# Filter by assignee and status
orbit -p myprofile jira issue list --assignee me --status "In Progress"

# Raw JQL query
orbit -p myprofile jira issue list --jql "project = PROJ AND sprint in openSprints()"

# JSON output for processing
orbit -p myprofile jira issue list --project PROJ -o json

# Fresh list — bypasses the JQL search index (useful right after transitions)
orbit -p myprofile jira issue list --jql "project = PROJ AND status = Open" --fresh

JQL 索引延迟 — issue list 会查询 Jira 的 JQL 搜索索引，该索引采用最终一致性，可能会比状态转换延迟 30–60 秒。当用户要求获取“当前”“最新”或“实时”的列表，或他们刚在同一会话中转换了某个工单时，请传入 --fresh，这样每一行都会通过权威的单问题端点重新验证。若不使用 --fresh，列表结果仅供参考；采取操作前，请务必使用 jira issue view KEY 重新验证单个键。

导出 Epic 层级结构

将完整的 Epic 层级结构（Epic → 故事 → 子任务）导出到结构化的 Markdown 目录中。

# Export a single epic
orbit -p myprofile jira export BS-1243 -O ./jira-export

# Export multiple epics
orbit -p myprofile jira export BS-1243 BS-1255 BS-1246 -O ./jira-export

输出结构：

<outdir>/<EPIC-KEY>/INDEX.md                    — epic metadata + story list
<outdir>/<EPIC-KEY>/<STORY-KEY>/INDEX.md        — story metadata + sub-task list
<outdir>/<EPIC-KEY>/<STORY-KEY>/<TASK-KEY>.md   — individual sub-task file

每个文件都包含元数据表（类型、状态、经办人、优先级、标签、故事点）以及从 Jira ADF 转换为 Markdown 的完整描述。使用 --max-results 控制每一层获取的子项数量（默认值：100）。

Sprint 管理

# List sprints on a board
orbit -p myprofile jira sprint list --board-id 42
orbit -p myprofile jira sprint list --board-id 42 --state active

# View sprint details
orbit -p myprofile jira sprint view 1366

# List issues in a sprint
orbit -p myprofile jira sprint list 1366

# Create a sprint
orbit -p myprofile jira sprint create --board-id 42 --name "Sprint 5" --start-date 2026-04-01 --end-date 2026-04-15

# Start a sprint
orbit -p myprofile jira sprint start 1366

# Close a sprint
orbit -p myprofile jira sprint close 1366

# Update sprint name/dates/goal
orbit -p myprofile jira sprint update 1366 --name "Sprint 5 Extended" --end-date 2026-04-20

# Add issues to a sprint
orbit -p myprofile jira sprint add 1366 PROJ-101 PROJ-102

# Move issues to backlog
orbit -p myprofile jira sprint remove PROJ-101 PROJ-102

# Delete a sprint
orbit -p myprofile jira sprint delete 1366

仪表板和小工具

以编程方式创建和管理 Jira 仪表板及小工具。

# List dashboards
orbit -p myprofile jira dashboard list
orbit -p myprofile jira dashboard list --filter "Sprint"

# Create a dashboard
orbit -p myprofile jira dashboard create --name "AI Metrics" --description "AI adoption tracking"

# View dashboard details
orbit -p myprofile jira dashboard view 10408

# Delete a dashboard
orbit -p myprofile jira dashboard delete 10408

# Add gadgets to a dashboard (use URI format for Cloud)
orbit -p myprofile jira dashboard gadget add 10408 \
  --uri "rest/gadgets/1.0/g/com.atlassian.jira.gadgets:filter-results-gadget/gadgets/filter-results-gadget.xml" \
  --title "My Filter Results" --color blue

# List gadgets on a dashboard
orbit -p myprofile jira dashboard gadget list 10408

# Remove a gadget
orbit -p myprofile jira dashboard gadget remove 10408 35501

# Configure gadget properties (e.g., bind a filter)
orbit -p myprofile jira dashboard gadget property set 10408 35501 config '{"filterId":"11233"}'
orbit -p myprofile jira dashboard gadget property get 10408 35501 config
orbit -p myprofile jira dashboard gadget property list 10408 35501

筛选器

创建、搜索和管理已保存的 JQL 筛选器。

# List favourite filters
orbit -p myprofile jira filter list

# Search all accessible filters
orbit -p myprofile jira filter search
orbit -p myprofile jira filter search --name "Sprint"

# View filter details
orbit -p myprofile jira filter view 10195

# Create a filter
orbit -p myprofile jira filter create --name "My Bugs" --jql "project = PROJ AND type = Bug" --favourite

# Update a filter
orbit -p myprofile jira filter update 10195 --jql "project = PROJ AND sprint in openSprints()"
orbit -p myprofile jira filter update 10195 --name "Active Sprint"

# Delete a filter
orbit -p myprofile jira filter delete 12345

字段管理（仅限 Cloud）

以编程方式管理自定义字段、其上下文和选项。

列出字段

# List all fields
orbit -p myprofile jira field list

# List only custom fields
orbit -p myprofile jira field list --custom

# Filter by name or ID
orbit -p myprofile jira field list --filter "AI"

创建自定义字段

# Create a select field (shorthand types: select, multiselect, number, checkbox, text, textarea)
orbit -p myprofile jira field create --name "AI Assisted" --type select \
  --description "Was AI used on this ticket?"

# Create a number field
orbit -p myprofile jira field create --name "AI Prompt Iterations" --type number \
  --description "How many prompt cycles to get working output"

# Create a checkbox field
orbit -p myprofile jira field create --name "Human Review Confirmed" --type checkbox \
  --description "Engineer confirms AI output was reviewed"

管理字段上下文和选项

# List field contexts
orbit -p myprofile jira field context-list customfield_10397

# List existing options
orbit -p myprofile jira field option-list customfield_10397 10817

# Add options to a select/multiselect field
orbit -p myprofile jira field option-add customfield_10397 10817 \
  --values "Yes,No,Partial"

屏幕管理

通过管理屏幕选项卡和字段分配，控制哪些字段会显示在问题创建、编辑和查看表单中。

列出屏幕和选项卡

# List all screens
orbit -p myprofile jira screen list

# Filter screens by name
orbit -p myprofile jira screen list --filter "PYMT"

# List tabs on a screen
orbit -p myprofile jira screen tab-list 10089

# List fields on a screen tab
orbit -p myprofile jira screen field-list 10089 10189

创建选项卡

# Create a new tab to group related fields
orbit -p myprofile jira screen tab-create 10089 "AI Workflow"

添加和移除字段

# Add fields to a screen tab
orbit -p myprofile jira screen field-add 10089 10868 \
  --fields "customfield_10397,customfield_10398,customfield_10399"

# Remove fields from a screen tab
orbit -p myprofile jira screen field-remove 10089 10189 \
  --fields "customfield_10397,customfield_10398"

在选项卡之间移动字段

# Move fields from General tab to AI Workflow tab
orbit -p myprofile jira screen field-move 10089 10189 10868 \
  --fields "customfield_10397,customfield_10398,customfield_10399"

状态和问题类型管理

列出工作流状态

# List all statuses with their categories
orbit -p myprofile jira status list

# Filter with grep
orbit -p myprofile jira status list | grep -i "review"

列出问题类型

orbit -p myprofile jira issuetype-list

删除问题

使用 issue delete 删除问题。使用 --cascade 同时删除所有子任务。

重要： 没有 --confirm 或 --force 标志。该命令会立即删除问题。

# Delete a single issue
orbit -p myprofile jira issue delete PROJ-123

# Delete an issue and all its subtasks
orbit -p myprofile jira issue delete PROJ-100 --cascade

删除层级结构（父项 → 子项 → 孙项）： 请自底向上删除，以避免出现孤立项错误；或者在每个包含子任务的层级使用 --cascade。

# Example: delete Story (with sub-tasks) → Epic → Capability
orbit -p myprofile jira issue delete PROJ-50 --cascade   # Story + sub-tasks
orbit -p myprofile jira issue delete PROJ-40              # Epic (now childless)
orbit -p myprofile jira issue delete PRT-200              # Capability (now childless)

提示： --cascade 只会删除 Jira 子任务（类型为 Sub-task 的子问题），不会删除 Epic 下的故事，也不会删除 Capability 下的 Epic。要删除完整的层级结构，请先使用 JQL 查询子项，然后自底向上删除。

# Find all children of an issue
orbit -p myprofile jira issue list --jql '"Parent" = PROJ-40' -o json

重要说明

• Cloud 与 Server — Atlassian Cloud 使用服务类型 jira-cloud（使用 API v3 和 ADF 描述）。Server/Data Center 使用 jira-onprem（使用 API v2 和 wiki 标记）。
• 描述格式 — 对于 Server 实例，--body 的值始终使用 Jira wiki 标记。对于 Cloud，orbit 会自动将纯文本转换为 ADF。wiki 标记语法请参阅 references/wiki-markup.md。
• 字段管理 — field create、field context-list、field option-list 和 field option-add 仅适用于 Cloud。
• 屏幕管理 — 将字段添加到屏幕后，这些字段会显示在问题创建和编辑表单中。使用 tab-create 将相关字段分组到专用选项卡中。
• Epic 类型不能使用 --parent 标志 — Jira 会拒绝该标志，因为 Epic 不是子任务类型。请改用 --field "customfield_27521=KEY"（Parent Link）。
• 密钥引用 - 配置中的凭据可以使用 1Password（op://vault/item/field）或 Infisical（infisical://<env>/<path>/<KEY>）引用，并在运行时解析。运行一次 orbit auth，即可解析并缓存所有密钥（使用 1Password 时只需进行一次生物识别提示）。使用 orbit auth clear 清除缓存。请参阅密钥。如果不运行 orbit auth，密钥仍会在每条命令执行时解析，但可能会反复触发生物识别提示。