Back to Details

jira

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Jira

Jira

Interact with Jira for issue tracking, search, and workflow management.
与Jira交互以进行问题追踪、搜索和工作流管理。

Installation

安装

  1. Install Python dependencies:
    bash
    pip install --user requests keyring pyyaml
  2. Download the skill from Releases or use directly from this repository.
  1. 安装Python依赖:
    bash
    pip install --user requests keyring pyyaml
  2. 下载Skill：从Releases下载，或直接使用本仓库中的内容。

Setup Verification

安装验证

After installation, verify the skill is properly configured:
bash
python scripts/jira.py check
This will check:
  • Python dependencies (requests, keyring, pyyaml)
  • Authentication configuration
  • Connectivity to Jira
If anything is missing, the check command will provide setup instructions.
安装完成后，验证Skill是否配置正确：
bash
python scripts/jira.py check
该命令将检查：
  • Python依赖（requests、keyring、pyyaml）是否安装
  • 身份验证配置情况
  • 与Jira的连接性
如果有缺失项，检查命令会提供对应的设置说明。

Authentication

身份验证

Configure Jira authentication using one of these methods:
通过以下任一方式配置Jira身份验证：

Option 1: Environment Variables (Recommended)

选项1：环境变量（推荐）

bash
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="your-token"
Add these to your 
~/.bashrc
or 
~/.zshrc
for persistence.
bash
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="your-token"
将上述命令添加到
~/.bashrc
或
~/.zshrc
中以持久化配置。

Option 2: Config File

选项2：配置文件

Create 
~/.config/agent-skills/jira.yaml
:
yaml
url: https://yourcompany.atlassian.net
email: you@example.com
token: your-token
创建
~/.config/agent-skills/jira.yaml
文件：
yaml
url: https://yourcompany.atlassian.net
email: you@example.com
token: your-token

Required Credentials

必填凭证

Rate Limits

速率限制

Atlassian Jira Cloud enforces rate limits to ensure fair usage and system stability. The specific limits vary based on your Jira instance type and plan:
  • Jira Cloud: Rate limits vary by endpoint and are enforced per-user and per-app
  • Jira Data Center/Server: Rate limits are typically configured by administrators
Atlassian Jira Cloud会实施速率限制，以确保公平使用和系统稳定性。具体限制因Jira实例类型和套餐而异：
  • Jira Cloud: 速率限制因接口而异，按用户和应用分别执行
  • Jira数据中心/服务器: 速率限制通常由管理员配置

Automatic Rate Limit Handling

自动速率限制处理

This skill automatically handles temporary rate limit errors (429 Too Many Requests) by:
  • Detecting rate limit responses from the Jira API
  • Waiting for the time specified in the 
    Retry-After
    header
  • Retrying failed requests up to 3 times with exponential backoff (1s, 2s, 4s)
  • Providing clear error messages if rate limits persist after all retry attempts
You don't need to manually handle rate limiting - the skill manages this automatically. If you encounter persistent rate limit errors, consider:
  • Reducing the frequency of API calls
  • Using 
    --max-results
    to limit the number of items returned
  • Spreading bulk operations over a longer time period
  • Contacting your Jira administrator if limits seem too restrictive
本Skill会自动处理临时速率限制错误（429请求过多），处理方式包括：
  • 检测Jira API返回的速率限制响应
  • 等待
    Retry-After
    头中指定的时间
  • 最多重试3次失败请求，采用指数退避策略（1秒、2秒、4秒）
  • 如果多次重试后仍触发速率限制，会提供清晰的错误提示
你无需手动处理速率限制 - Skill会自动管理。如果持续遇到速率限制错误，可以考虑：
  • 减少API调用频率
  • 使用
    --max-results
    限制返回结果数量
  • 将批量操作分散到更长的时间段内
  • 如果限制过于严格，联系你的Jira管理员

Best Practices for AI Agents

AI Agent最佳实践

When using this skill for bulk operations or automated workflows:
  1. Use specific JQL queries to minimize the number of API calls needed
  2. Leverage configuration defaults and JQL scope to avoid redundant filters
  3. Use 
    --max-results
    appropriately - don't fetch more data than needed
  4. For large datasets, consider paginating manually with multiple smaller queries
  5. Be aware that search operations may be more heavily rate-limited than direct issue access
当使用本Skill进行批量操作或自动化工作流时：
  1. 使用具体的JQL查询，尽量减少所需的API调用次数
  2. 利用配置默认值和JQL范围，避免重复过滤
  3. 合理使用
    --max-results
    - 不要获取超出需要的数据
  4. 对于大型数据集，考虑通过多个较小的查询手动分页
  5. 注意搜索操作的速率限制可能比直接访问问题更严格

Configuration Defaults

配置默认值

Optionally configure defaults in 
~/.config/agent-skills/jira.yaml
to reduce repetitive typing:
yaml
undefined
可在
~/.config/agent-skills/jira.yaml
中配置默认值，减少重复输入：
yaml
undefined

Authentication (optional if using environment variables)

身份验证（如果使用环境变量则可选）

url: https://yourcompany.atlassian.net email: you@example.com token: your-token
url: https://yourcompany.atlassian.net email: you@example.com token: your-token

Optional defaults

可选默认值

defaults: jql_scope: "project = DEMO AND assignee = currentUser()" security_level: "Red Hat Internal" max_results: 25 fields: ["summary", "status", "assignee", "priority", "created"]
defaults: jql_scope: "project = DEMO AND assignee = currentUser()" security_level: "Red Hat Internal" max_results: 25 fields: ["summary", "status", "assignee", "priority", "created"]

Optional project-specific defaults

可选项目特定默认值

projects: DEMO: issue_type: "Task" priority: "Medium" PROD: issue_type: "Bug" priority: "High"
undefined
projects: DEMO: issue_type: "Task" priority: "Medium" PROD: issue_type: "Bug" priority: "High"
undefined

How Defaults Work

默认值生效规则

  • CLI arguments always override config defaults
  • JQL scope is prepended to all searches: 
    (scope) AND (your_query)
  • Security level applies to comments and transitions with comments
  • Project defaults apply when creating issues in that project
  • CLI参数始终覆盖配置默认值
  • JQL范围会自动添加到所有搜索前：
    (范围) AND (你的查询)
  • 安全级别适用于带评论的操作和状态转换
  • 项目默认值在该项目中创建问题时生效

View Configuration

查看配置

bash
undefined
bash
undefined

Show all configuration

查看所有配置

python scripts/jira.py config show
python scripts/jira.py config show

Show project-specific defaults

查看项目特定默认值

python scripts/jira.py config show --project DEMO
undefined
python scripts/jira.py config show --project DEMO
undefined

Commands

命令

check

check

Verify configuration and connectivity.
bash
python scripts/jira.py check
This validates:
  • Python dependencies are installed
  • Authentication is configured
  • Can connect to Jira
  • API version is detected correctly
验证配置和连接性。
bash
python scripts/jira.py check
该命令会验证：
  • Python依赖已安装
  • 身份验证已配置
  • 可连接到Jira
  • API版本已正确检测

search

search

Search for issues using JQL (Jira Query Language).
bash
undefined
使用JQL（Jira查询语言）搜索问题。
bash
undefined

Standard JQL

标准JQL

python scripts/jira.py search "project = DEMO AND status = Open" python scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20
python scripts/jira.py search "project = DEMO AND status = Open" python scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20

ScriptRunner Enhanced Search (if available)

ScriptRunner增强搜索（如果可用）

Find issues linked to a specific issue

查找与特定问题关联的问题

python scripts/jira.py search 'issue in linkedIssuesOf("DEMO-123")'
python scripts/jira.py search 'issue in linkedIssuesOf("DEMO-123")'

Find parent/child relationships

查找父/子关系

python scripts/jira.py search 'issue in parentsOf("DEMO-123")' python scripts/jira.py search 'issue in subtasksOf("DEMO-123")'
python scripts/jira.py search 'issue in parentsOf("DEMO-123")' python scripts/jira.py search 'issue in subtasksOf("DEMO-123")'

Find issues commented on by a specific user

查找特定用户评论过的问题

python scripts/jira.py search 'issue in commentedByUser("username")'
python scripts/jira.py search 'issue in commentedByUser("username")'

Find epics and their issues

查找史诗及其关联问题

python scripts/jira.py search 'issue in epicsOf("DEMO-123")' python scripts/jira.py search 'issue in issuesInEpics("EPIC-123")'
python scripts/jira.py search 'issue in epicsOf("DEMO-123")' python scripts/jira.py search 'issue in issuesInEpics("EPIC-123")'

Find issues with specific link types (dependencies, blocks, etc.)

查找带有特定链接类型的问题（依赖、阻塞等）

python scripts/jira.py search 'issue in hasLinkType("Dependency")'

**Arguments:**
- `jql`: JQL query string (required) - supports ScriptRunner functions if installed
- `--max-results`: Maximum number of results (default: 50)
- `--fields`: Comma-separated list of fields to include
- `--json`: Output as JSON

**ScriptRunner Support:**

The skill automatically detects if ScriptRunner Enhanced Search is installed and validates queries that use advanced JQL functions. If ScriptRunner functions are detected but the plugin is not available, you'll receive a warning.

Common ScriptRunner functions include:
- `linkedIssuesOf()`, `hasLinkType()` - Link and dependency queries
- `subtasksOf()`, `parentsOf()`, `epicsOf()` - Hierarchy navigation
- `commentedByUser()`, `transitionedBy()` - User activity tracking
- And many more...

**For complete ScriptRunner guidance** including user lookups, practical examples, and troubleshooting, read [scriptrunner.md](references/scriptrunner.md).

Note: ScriptRunner works differently on Cloud vs Data Center/Server instances. The skill handles both automatically.
python scripts/jira.py search 'issue in hasLinkType("Dependency")'

**参数:**
- `jql`: JQL查询字符串（必填）- 如果已安装ScriptRunner，则支持其扩展函数
- `--max-results`: 最大返回结果数（默认：50）
- `--fields`: 要包含的字段列表，用逗号分隔
- `--json`: 以JSON格式输出

**ScriptRunner支持:**

本Skill会自动检测是否安装了ScriptRunner增强搜索，并验证使用高级JQL函数的查询。如果检测到ScriptRunner函数但插件不可用，你会收到警告。

常见的ScriptRunner函数包括：
- `linkedIssuesOf()`、`hasLinkType()` - 链接和依赖查询
- `subtasksOf()`、`parentsOf()`、`epicsOf()` - 层级导航
- `commentedByUser()`、`transitionedBy()` - 用户活动追踪
- 以及更多...

**完整ScriptRunner指南**包括用户查找、实用示例和故障排除，请阅读[scriptrunner.md](references/scriptrunner.md)。

注意：ScriptRunner在Cloud和数据中心/服务器实例上的工作方式不同，本Skill会自动适配两种环境。

issue

issue

Get, create, update, or comment on issues.
bash
undefined
获取、创建、更新问题或添加评论。
bash
undefined

Get issue details

获取问题详情

python scripts/jira.py issue get DEMO-123
python scripts/jira.py issue get DEMO-123

Get issue with specific fields only

仅获取问题的特定字段

python scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee"
python scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee"

Create new issue

创建新问题

python scripts/jira.py issue create --project DEMO --type Task --summary "New task"
python scripts/jira.py issue create --project DEMO --type Task --summary "New task"

Update issue

更新问题

python scripts/jira.py issue update DEMO-123 --summary "Updated summary"
python scripts/jira.py issue update DEMO-123 --summary "Updated summary"

Add comment

添加评论

python scripts/jira.py issue comment DEMO-123 "This is a comment"
python scripts/jira.py issue comment DEMO-123 "This is a comment"

Add private comment with security level

添加带安全级别的私密评论

python scripts/jira.py issue comment DEMO-123 "Internal note" --security-level "Red Hat Internal"

**Arguments for `issue get`:**
- `issue_key`: Issue key (required)
- `--fields`: Comma-separated list of fields to include (uses config default if not specified)
- `--json`: Output as JSON
python scripts/jira.py issue comment DEMO-123 "Internal note" --security-level "Red Hat Internal"

**`issue get`参数:**
- `issue_key`: 问题键（必填）
- `--fields`: 要包含的字段列表，用逗号分隔（如果未指定则使用配置默认值）
- `--json`: 以JSON格式输出

transitions

transitions

Manage issue workflow transitions.
bash
undefined
管理问题工作流状态转换。
bash
undefined

List available transitions

列出可用的状态转换

python scripts/jira.py transitions list DEMO-123
python scripts/jira.py transitions list DEMO-123

Transition issue

执行状态转换

python scripts/jira.py transitions do DEMO-123 "In Progress" python scripts/jira.py transitions do DEMO-123 "Done" --comment "Completed"
python scripts/jira.py transitions do DEMO-123 "In Progress" python scripts/jira.py transitions do DEMO-123 "Done" --comment "Completed"

Transition with private comment

执行带私密评论的状态转换

python scripts/jira.py transitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Red Hat Internal"
undefined
python scripts/jira.py transitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Red Hat Internal"
undefined

config

config

Manage configuration and view effective defaults.
bash
undefined
管理配置并查看生效的默认值。
bash
undefined

Show all configuration and defaults

查看所有配置和默认值

python scripts/jira.py config show
python scripts/jira.py config show

Show project-specific defaults

查看项目特定默认值

python scripts/jira.py config show --project DEMO

This displays:
- Authentication settings (with masked token)
- Default JQL scope, security level, max results, and fields
- Project-specific defaults for issue type and priority
python scripts/jira.py config show --project DEMO

该命令会显示：
- 身份验证设置（令牌会被掩码处理）
- 默认JQL范围、安全级别、最大结果数和字段
- 项目特定的问题类型和优先级默认值

fields

fields

List available fields in your Jira instance.
bash
undefined
列出Jira实例中的可用字段。
bash
undefined

List all global fields

列出所有全局字段

python scripts/jira.py fields
python scripts/jira.py fields

List fields for specific project and issue type

列出特定项目和问题类型的字段

python scripts/jira.py fields --project DEMO --issue-type Task
python scripts/jira.py fields --project DEMO --issue-type Task

Output as JSON

以JSON格式输出

python scripts/jira.py fields --json

**Arguments:**
- `--project`: Project key for context-specific fields
- `--issue-type`: Issue type name (requires --project)
- `--json`: Output as JSON

**Note:** Fields vary by project and issue type. When creating or searching issues, use `--project` and `--issue-type` to see only the fields available in that context.
python scripts/jira.py fields --json

**参数:**
- `--project`: 用于上下文特定字段的项目键
- `--issue-type`: 问题类型名称（需要搭配--project使用）
- `--json`: 以JSON格式输出

**注意:** 字段因项目和问题类型而异。创建或搜索问题时，使用`--project`和`--issue-type`查看该上下文中的可用字段。

statuses

statuses

List available statuses and status categories.
bash
undefined
列出可用的状态和状态类别。
bash
undefined

List all statuses

列出所有状态

python scripts/jira.py statuses
python scripts/jira.py statuses

List status categories (To Do, In Progress, Done)

列出状态类别（待办、进行中、已完成）

python scripts/jira.py statuses --categories
python scripts/jira.py statuses --categories

Output as JSON

以JSON格式输出

python scripts/jira.py statuses --json

**Arguments:**
- `--categories`: Show status categories instead of individual statuses
- `--json`: Output as JSON

**Recommendation:** Use `statusCategory` in JQL queries for more portable queries:
- `statusCategory = "To Do"` - matches all statuses in the To Do category
- `statusCategory = "In Progress"` - matches all in-progress statuses
- `statusCategory = Done` - matches all completed statuses

This is more reliable than using specific status names, which vary between projects.
python scripts/jira.py statuses --json

**参数:**
- `--categories`: 显示状态类别而非单个状态
- `--json`: 以JSON格式输出

**建议:** 在JQL查询中使用`statusCategory`，使查询更具可移植性：
- `statusCategory = "To Do"` - 匹配所有待办类别中的状态
- `statusCategory = "In Progress"` - 匹配所有进行中的状态
- `statusCategory = Done` - 匹配所有已完成的状态

这比使用特定状态名称更可靠，因为状态名称在不同项目中可能不同。

Examples

示例

Verify Setup

验证安装

bash
python scripts/jira.py check
bash
python scripts/jira.py check

Find my open issues

查找我的未完成问题

bash
python scripts/jira.py search "assignee = currentUser() AND status != Done ORDER BY priority DESC"
bash
python scripts/jira.py search "assignee = currentUser() AND status != Done ORDER BY priority DESC"

Create a bug report

创建Bug报告

bash
python scripts/jira.py issue create \
  --project DEMO \
  --type Bug \
  --summary "Login button not working" \
  --description "The login button on the homepage does not respond to clicks."
bash
python scripts/jira.py issue create \
  --project DEMO \
  --type Bug \
  --summary "Login button not working" \
  --description "The login button on the homepage does not respond to clicks."

Move issue through workflow

执行问题状态转换

bash
undefined
bash
undefined

Start work on an issue

开始处理问题

python scripts/jira.py transitions do DEMO-123 "In Progress"
python scripts/jira.py transitions do DEMO-123 "In Progress"

Complete the issue

完成问题

python scripts/jira.py transitions do DEMO-123 "Done" --comment "Implemented and tested"
undefined
python scripts/jira.py transitions do DEMO-123 "Done" --comment "Implemented and tested"
undefined

Add private comment

添加私密评论

bash
undefined
bash
undefined

Add comment visible only to specific security level

添加仅特定安全级别可见的评论

python scripts/jira.py issue comment DEMO-123
"This is sensitive internal information"
--security-level "Red Hat Internal"
undefined
python scripts/jira.py issue comment DEMO-123
"This is sensitive internal information"
--security-level "Red Hat Internal"
undefined

Search with specific fields

搜索特定字段

bash
python scripts/jira.py search \
  "project = DEMO AND created >= -7d" \
  --fields "key,summary,status,assignee,created"
bash
python scripts/jira.py search \
  "project = DEMO AND created >= -7d" \
  --fields "key,summary,status,assignee,created"

Using Configuration Defaults

使用配置默认值

With defaults configured as shown in the Configuration Defaults section:
bash
undefined
按照配置默认值部分所示配置默认值后：
bash
undefined

Search uses JQL scope automatically

搜索会自动使用JQL范围

python scripts/jira.py search "status = Open"
python scripts/jira.py search "status = Open"

Becomes: (project = DEMO AND assignee = currentUser()) AND (status = Open)

实际执行的查询：(project = DEMO AND assignee = currentUser()) AND (status = Open)

Search with automatic max_results and fields from config

搜索会自动使用配置中的max_results和字段

python scripts/jira.py search "priority = High"
python scripts/jira.py search "priority = High"

Uses configured max_results (25) and fields automatically

自动使用配置的max_results(25)和字段

Create issue uses project defaults

创建问题时使用项目默认值

python scripts/jira.py issue create --project DEMO --summary "Fix login bug"
python scripts/jira.py issue create --project DEMO --summary "Fix login bug"

Automatically uses issue_type="Task" and priority="Medium" from DEMO project defaults

自动使用DEMO项目默认的issue_type="Task"和priority="Medium"

Comments use default security level

评论会使用默认安全级别

python scripts/jira.py issue comment DEMO-123 "Internal note"
python scripts/jira.py issue comment DEMO-123 "Internal note"

Automatically applies security_level="Red Hat Internal"

自动应用security_level="Red Hat Internal"

Override defaults when needed

需要时可覆盖默认值

python scripts/jira.py search "status = Open" --max-results 100
python scripts/jira.py search "status = Open" --max-results 100

CLI argument overrides the configured default of 25

CLI参数会覆盖配置的默认值25

undefined
undefined

JQL Reference

JQL参考

Common JQL queries:
QueryDescription
project = DEMO
Issues in DEMO project
assignee = currentUser()
Issues assigned to you
status = "In Progress"
Issues in progress
created >= -7d
Created in last 7 days
updated >= startOfDay()
Updated today
priority = High
High priority issues
labels = "bug"
Issues with "bug" label
Combine with 
AND
, 
OR
, and use 
ORDER BY
for sorting.
常见JQL查询：
查询描述
project = DEMO
DEMO项目中的问题
assignee = currentUser()
分配给你的问题
status = "In Progress"
进行中的问题
created >= -7d
过去7天创建的问题
updated >= startOfDay()
今天更新的问题
priority = High
高优先级问题
labels = "bug"
带有"bug"标签的问题
可使用
AND
、
OR
组合查询，并使用
ORDER BY
进行排序。

Status Categories

状态类别

Jira organizes all statuses into three categories. Use 
statusCategory
for queries that work across projects:
CategoryMeaningExample Statuses
To DoNot startedOpen, Backlog, New
In ProgressBeing worked onIn Development, In Review
DoneCompletedClosed, Resolved, Done
Example: Instead of 
status = "Open" OR status = "Backlog"
, use 
statusCategory = "To Do"
.
Use 
python scripts/jira.py statuses --categories
to see all status categories in your Jira instance.
Jira将所有状态分为三个类别。使用
statusCategory
编写可跨项目使用的查询：
类别含义示例状态
To Do未开始Open, Backlog, New
In Progress处理中In Development, In Review
Done已完成Closed, Resolved, Done
示例: 不要使用
status = "Open" OR status = "Backlog"
，而是使用
statusCategory = "To Do"
。
使用
python scripts/jira.py statuses --categories
查看你的Jira实例中的所有状态类别。

Model Guidance

模型使用指导

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.
本Skill会进行需要结构化输入/输出的API调用。推荐使用具备标准能力的模型。

Troubleshooting

故障排除

Check command fails

check命令执行失败

Run 
python scripts/jira.py check
to diagnose issues. It will provide specific error messages and setup instructions.
运行
python scripts/jira.py check
诊断问题，它会提供具体的错误信息和设置说明。

Authentication failed

身份验证失败

  1. Verify your API token is correct
  2. Ensure you're using your email (not username)
  3. For Jira Cloud, use your Atlassian account email
  4. For Jira Data Center/Server, use your username
  1. 验证你的API令牌是否正确
  2. 确保使用的是邮箱（而非用户名）
  3. 对于Jira Cloud，使用你的Atlassian账户邮箱
  4. 对于Jira数据中心/服务器，使用你的用户名

Permission denied

权限被拒绝

You may not have access to the requested project or issue. Contact your Jira administrator.
你可能没有访问请求的项目或问题的权限，请联系你的Jira管理员。

JQL syntax error

JQL语法错误

Use the Jira web interface to test your JQL query before using it in scripts.
在脚本中使用JQL查询前，先在Jira网页界面中测试该查询。

Import errors

导入错误

Ensure dependencies are installed:
bash
pip install --user requests keyring pyyaml
确保已安装所有依赖：
bash
pip install --user requests keyring pyyaml