Back to Details

jira-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Jira Integration Skill

Jira集成Skill

Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both MCP-based (recommended) and direct REST API approaches.
可直接在你的AI编码工作流中检索、分析和更新Jira工单，同时支持基于MCP（推荐）和直接调用REST API两种方式。

When to Activate

何时启用

  • Fetching a Jira ticket to understand requirements
  • Extracting testable acceptance criteria from a ticket
  • Adding progress comments to a Jira issue
  • Transitioning a ticket status (To Do → In Progress → Done)
  • Linking merge requests or branches to a Jira issue
  • Searching for issues by JQL query
  • 获取Jira工单以了解需求
  • 从工单中提取可测试的验收标准
  • 为Jira问题添加进度评论
  • 流转工单状态（待办 → 进行中 → 已完成）
  • 将合并请求或分支关联到Jira问题
  • 通过JQL查询搜索问题

Prerequisites

前置条件

Option A: MCP Server (Recommended)

选项A：MCP服务器（推荐）

Install the 
mcp-atlassian
MCP server. This exposes Jira tools directly to your AI agent.
Requirements:
  • Python 3.10+
  • uvx
    (from 
    uv
    ), installed via your package manager or the official 
    uv
    installation documentation
Add to your MCP config (e.g., 
~/.claude.json
→ 
mcpServers
):
json
{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira issue tracking — search, create, update, comment, transition"
  }
}
Security: Never hardcode secrets. Prefer setting 
JIRA_URL
, 
JIRA_EMAIL
, and 
JIRA_API_TOKEN
in your system environment (or a secrets manager). Only use the MCP 
env
block for local, uncommitted config files.
To get a Jira API token:
  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click Create API token
  3. Copy the token — store it in your environment, never in source code
安装
mcp-atlassian
MCP服务器，它会直接向你的AI Agent暴露Jira工具能力。
要求：
  • Python 3.10+
  • uvx
    （来自
    uv
    ），可通过包管理器或官方
    uv
    安装文档进行安装
添加到你的MCP配置中（例如
~/.claude.json
的
mcpServers
字段）：
json
{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira问题追踪 — 搜索、创建、更新、评论、状态流转"
  }
}
安全提示： 永远不要硬编码密钥。建议将
JIRA_URL
、
JIRA_EMAIL
和
JIRA_API_TOKEN
配置在系统环境变量（或密钥管理器）中。仅在本地未提交的配置文件中使用MCP的
env
配置块。
获取Jira API token的方法：
  1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens
  2. 点击创建API token
  3. 复制token并存到你的环境变量中，永远不要提交到源代码

Option B: Direct REST API

选项B：直接调用REST API

If MCP is not available, use the Jira REST API v3 directly via 
curl
or a helper script.
Required environment variables:
VariableDescription
JIRA_URL
Your Jira instance URL (e.g., 
https://yourorg.atlassian.net
)
JIRA_EMAIL
Your Atlassian account email
JIRA_API_TOKEN
API token from id.atlassian.com
Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo.
如果无法使用MCP，可以通过
curl
或辅助脚本直接调用Jira REST API v3。
所需环境变量：
变量描述
JIRA_URL
你的Jira实例地址（例如
https://yourorg.atlassian.net
）
JIRA_EMAIL
你的Atlassian账号邮箱
JIRA_API_TOKEN
从id.atlassian.com获取的API token
将这些变量存储在你的shell环境、密钥管理器或未被追踪的本地env文件中，不要提交到代码仓库。

MCP Tools Reference

MCP工具参考

When the 
mcp-atlassian
MCP server is configured, these tools are available:
ToolPurposeExample
jira_search
JQL queries
project = PROJ AND status = "In Progress"
jira_get_issue
Fetch full issue details by key
PROJ-1234
jira_create_issue
Create issues (Task, Bug, Story, Epic)New bug report
jira_update_issue
Update fields (summary, description, assignee)Change assignee
jira_transition_issue
Change statusMove to "In Review"
jira_add_comment
Add commentsProgress update
jira_get_sprint_issues
List issues in a sprintActive sprint review
jira_create_issue_link
Link issues (Blocks, Relates to)Dependency tracking
jira_get_issue_development_info
See linked PRs, branches, commitsDev context
Tip: Always call 
jira_get_transitions
before transitioning — transition IDs vary per project workflow.
配置好
mcp-atlassian
MCP服务器后，你可以使用以下工具：
工具用途示例
jira_search
JQL查询
project = PROJ AND status = "In Progress"
jira_get_issue
通过工单key获取完整问题详情
PROJ-1234
jira_create_issue
创建问题（任务、Bug、需求、史诗）新Bug报告
jira_update_issue
更新字段（标题、描述、负责人）更换负责人
jira_transition_issue
变更状态移动到「审核中」
jira_add_comment
添加评论进度更新
jira_get_sprint_issues
列出某个迭代中的所有问题活跃迭代复盘
jira_create_issue_link
关联问题（阻塞、关联）依赖追踪
jira_get_issue_development_info
查看关联的PR、分支、提交开发上下文
提示： 流转状态前请先调用
jira_get_transitions
— 不同项目的工作流对应的流转ID不一样。

Direct REST API Reference

直接REST API参考

Fetch a Ticket

获取工单

bash
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'
bash
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'

Fetch Comments

获取评论

bash
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'
bash
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'

Add a Comment

添加评论

bash
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "Your comment here"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"
bash
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "Your comment here"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

Transition a Ticket

流转工单状态

bash
undefined
bash
undefined

1. Get available transitions

1. 获取可用的流转选项

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN"
"$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN"
"$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

2. Execute transition (replace TRANSITION_ID)

2. 执行状态流转（替换TRANSITION_ID）

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN"
-H "Content-Type: application/json"
-d '{"transition": {"id": "TRANSITION_ID"}}'
"$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"
undefined
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN"
-H "Content-Type: application/json"
-d '{"transition": {"id": "TRANSITION_ID"}}'
"$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"
undefined

Search with JQL

用JQL搜索

bash
curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"
bash
curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"

Analyzing a Ticket

工单分析

When retrieving a ticket for development or test automation, extract:
当你拉取工单用于开发或测试自动化时，请提取以下信息：

1. Testable Requirements

1. 可测试需求

  • Functional requirements — What the feature does
  • Acceptance criteria — Conditions that must be met
  • Testable behaviors — Specific actions and expected outcomes
  • User roles — Who uses this feature and their permissions
  • Data requirements — What data is needed
  • Integration points — APIs, services, or systems involved
  • 功能需求 — 该特性的作用是什么
  • 验收标准 — 必须满足的条件
  • 可测试行为 — 具体操作和预期结果
  • 用户角色 — 谁使用该特性以及对应的权限
  • 数据要求 — 需要用到哪些数据
  • 集成点 — 涉及的API、服务或系统

2. Test Types Needed

2. 所需测试类型

  • Unit tests — Individual functions and utilities
  • Integration tests — API endpoints and service interactions
  • E2E tests — User-facing UI flows
  • API tests — Endpoint contracts and error handling
  • 单元测试 — 单个函数和工具方法
  • 集成测试 — API端点和服务交互
  • E2E测试 — 用户侧UI流程
  • API测试 — 端点契约和错误处理

3. Edge Cases & Error Scenarios

3. 边界情况与错误场景

  • Invalid inputs (empty, too long, special characters)
  • Unauthorized access
  • Network failures or timeouts
  • Concurrent users or race conditions
  • Boundary conditions
  • Missing or null data
  • State transitions (back navigation, refresh, etc.)
  • 无效输入（空值、过长、特殊字符）
  • 未授权访问
  • 网络故障或超时
  • 并发用户或竞态条件
  • 边界值条件
  • 缺失或空数据
  • 状态流转（回退、刷新等）

4. Structured Analysis Output

4. 结构化分析输出

Ticket: PROJ-1234
Summary: [ticket title]
Status: [current status]
Priority: [High/Medium/Low]
Test Types: Unit, Integration, E2E

Requirements:
1. [requirement 1]
2. [requirement 2]

Acceptance Criteria:
- [ ] [criterion 1]
- [ ] [criterion 2]

Test Scenarios:
- Happy Path: [description]
- Error Case: [description]
- Edge Case: [description]

Test Data Needed:
- [data item 1]
- [data item 2]

Dependencies:
- [dependency 1]
- [dependency 2]
工单: PROJ-1234
标题: [工单标题]
状态: [当前状态]
优先级: [高/中/低]
测试类型: 单元测试, 集成测试, E2E测试

需求:
1. [需求1]
2. [需求2]

验收标准:
- [ ] [标准1]
- [ ] [标准2]

测试场景:
- 正常路径: [描述]
- 错误场景: [描述]
- 边界场景: [描述]

所需测试数据:
- [数据项1]
- [数据项2]

依赖项:
- [依赖1]
- [依赖2]

Updating Tickets

工单更新

When to Update

何时更新

Workflow StepJira Update
Start workTransition to "In Progress"
Tests writtenComment with test coverage summary
Branch createdComment with branch name
PR/MR createdComment with link, link issue
Tests passingComment with results summary
PR/MR mergedTransition to "Done" or "In Review"
工作流步骤Jira更新操作
开始工作流转到「进行中」
测试编写完成评论说明测试覆盖率概况
创建分支评论附上分支名称
创建PR/MR评论附上PR链接，关联工单
测试通过评论附上测试结果概况
PR/MR合并流转到「已完成」或「审核中」

Comment Templates

评论模板

Starting Work:
Starting implementation for this ticket.
Branch: feat/PROJ-1234-feature-name
Tests Implemented:
Automated tests implemented:

Unit Tests:
- [test file 1] — [what it covers]
- [test file 2] — [what it covers]

Integration Tests:
- [test file] — [endpoints/flows covered]

All tests passing locally. Coverage: XX%
PR Created:
Pull request created:
[PR Title](https://github.com/org/repo/pull/XXX)

Ready for review.
Work Complete:
Implementation complete.

PR merged: [link]
Test results: All passing (X/Y)
Coverage: XX%
开始工作：
开始实现该工单需求。
分支: feat/PROJ-1234-feature-name
测试实现完成：
已实现自动化测试：

单元测试:
- [测试文件1] — [覆盖范围]
- [测试文件2] — [覆盖范围]

集成测试:
- [测试文件] — [覆盖的端点/流程]

所有测试本地运行通过。覆盖率: XX%
PR已创建：
已提交Pull Request:
[PR标题](https://github.com/org/repo/pull/XXX)

可进行审核。
工作完成：
需求实现完成。

PR已合并: [链接]
测试结果: 全部通过 (X/Y)
覆盖率: XX%

Security Guidelines

安全指南

  • Never hardcode Jira API tokens in source code or skill files
  • Always use environment variables or a secrets manager
  • Add 
    .env
     to 
    .gitignore
    in every project
  • Rotate tokens immediately if exposed in git history
  • Use least-privilege API tokens scoped to required projects
  • Validate that credentials are set before making API calls — fail fast with a clear message
  • 永远不要在源代码或技能文件中硬编码Jira API token
  • 始终使用环境变量或密钥管理器存储凭证
  • 在所有项目的
    .gitignore
    中添加
    .env
  • 如果token泄露到git历史中，立即轮换
  • 使用最小权限的API token，仅授予所需项目的访问权限
  • 发起API调用前校验凭证是否已配置 — 快速失败并给出明确提示

Troubleshooting

问题排查

ErrorCauseFix
401 Unauthorized
Invalid or expired API tokenRegenerate at id.atlassian.com
403 Forbidden
Token lacks project permissionsCheck token scopes and project access
404 Not Found
Wrong ticket key or base URLVerify 
JIRA_URL
and ticket key
spawn uvx ENOENT
IDE cannot find 
uvx
on PATH		Use full path (e.g., 
~/.local/bin/uvx
) or set PATH in 
~/.zprofile
Connection timeoutNetwork/VPN issueCheck VPN connection and firewall rules
错误原因解决方法
401 Unauthorized
API token无效或已过期到id.atlassian.com重新生成
403 Forbidden
Token没有项目权限检查token权限范围和项目访问权限
404 Not Found
工单key或基础URL错误校验
JIRA_URL
和工单key是否正确
spawn uvx ENOENT
IDE在PATH中找不到
uvx
使用完整路径（例如
~/.local/bin/uvx
）或者在
~/.zprofile
中配置PATH
连接超时网络/VPN问题检查VPN连接和防火墙规则

Best Practices

最佳实践

  • Update Jira as you go, not all at once at the end
  • Keep comments concise but informative
  • Link rather than copy — point to PRs, test reports, and dashboards
  • Use @mentions if you need input from others
  • Check linked issues to understand full feature scope before starting
  • If acceptance criteria are vague, ask for clarification before writing code
  • 随工作进度同步更新Jira，不要等到最后一次性更新
  • 评论简洁但信息完整
  • 优先使用链接而非复制内容 — 指向PR、测试报告和看板
  • 如果你需要其他人的输入请使用@提及
  • 开始开发前先检查关联问题，了解完整的特性范围
  • 如果验收标准模糊，先询问清楚再编写代码