Back to Details

jira-issue-relationships

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

jira-relationships

jira-relationships

Issue linking and dependency management for JIRA - create, view, and analyze issue relationships.
面向JIRA的问题关联与依赖管理——创建、查看并分析问题关联关系。

Risk Levels

风险等级

OperationRiskNotes
Get link types
-
Read-only
Get links/blockers
-
Read-only
Get dependencies
-
Read-only
Link statistics
-
Read-only
Create link
-
Easily reversible (can unlink)
Remove link
!
Link data lost, can recreate
Bulk link
!
Many links created, can remove
Clone issue
-
Creates new issue, can delete
Clone with subtasks
!
Creates multiple issues
Risk Legend: 
-
Safe, read-only | 
!
Caution, modifiable | 
!!
Warning, destructive but recoverable | 
!!!
Danger, irreversible
操作风险说明
获取链接类型
-
只读
获取链接/阻塞项
-
只读
获取依赖关系
-
只读
链接统计
-
只读
创建链接
-
可轻松撤销（可取消链接）
删除链接
!
链接数据丢失，可重新创建
批量链接
!
会创建大量链接，可删除
克隆问题
-
创建新问题，可删除
克隆含子任务的问题
!
会创建多个问题
风险图例：
-
安全，只读 | 
!
注意，可修改 | 
!!
警告，破坏性但可恢复 | 
!!!
危险，不可逆

When to use this skill

何时使用该Skill

Use this skill when you need to:
  • Link issues together (blocks, duplicates, relates to, clones)
  • View issue dependencies and blockers
  • Find blocker chains and critical paths
  • Analyze issue relationships and dependencies
  • Get link statistics for issues or projects
  • Bulk link multiple issues
  • Clone issues with their relationships
在以下场景中使用该Skill：
  • 关联问题（阻塞、重复、相关、克隆）
  • 查看问题依赖关系与阻塞项
  • 查找阻塞链与关键路径
  • 分析问题关联关系与依赖
  • 获取问题或项目的链接统计数据
  • 批量关联多个问题
  • 克隆带有关联关系的问题

What this skill does

该Skill的功能

IMPORTANT: Always use the 
jira-as
CLI. Never run Python scripts directly.
This skill provides issue relationship operations:
  1. Get Link Types: View available link types in JIRA instance
    • Lists all configured link types
    • Shows inward/outward descriptions
    • Filter by name pattern
  2. Link Issues: Create relationships between issues
    • Semantic flags for common types (--blocks, --relates-to, etc.)
    • Support for all JIRA link types
    • Optional comment on link creation
    • Dry-run mode for preview
  3. View Links: See all relationships for an issue
    • Filter by direction (inward/outward)
    • Filter by link type
    • Shows linked issue status and summary
  4. Remove Links: Delete issue relationships
    • Remove specific links between issues
    • Remove all links of a type
    • Dry-run and confirmation modes
  5. Blocker Analysis: Find blocking dependencies
    • Direct blockers for an issue
    • Recursive blocker chain traversal
    • Circular dependency detection
    • Critical path identification
  6. Dependency Graphs: Visualize relationships
    • Export to DOT format for Graphviz
    • Export to Mermaid diagrams
    • Export to PlantUML format
    • Export to D2 diagrams (Terrastruct)
    • Transitive dependency tracking
  7. Link Statistics: Analyze link patterns
    • Stats for single issue or entire project
    • Link breakdown by type and direction
    • Find orphaned issues (no links)
    • Identify most-connected issues
    • Status distribution of linked issues
  8. Bulk Operations: Link multiple issues at once
    • Link from JQL query results
    • Progress tracking
    • Skip existing links
  9. Clone Issues: Duplicate issues with relationships
    • Copy fields to new issue
    • Create "clones" link to original
    • Optionally copy subtasks and links
重要提示：请始终使用
jira-as
CLI。切勿直接运行Python脚本。
该Skill提供以下问题关联操作：
  1. 获取链接类型：查看JIRA实例中可用的链接类型
    • 列出所有已配置的链接类型
    • 显示内向/外向描述
    • 按名称模式筛选
  2. 关联问题：创建问题之间的关联关系
    • 常见类型的语义标记（--blocks、--relates-to等）
    • 支持所有JIRA链接类型
    • 关联创建时可添加可选注释
    • 预览模式（Dry-run）
  3. 查看链接：查看某一问题的所有关联关系
    • 按方向筛选（内向/外向）
    • 按链接类型筛选
    • 显示关联问题的状态与摘要
  4. 删除链接：删除问题关联关系
    • 删除特定问题之间的链接
    • 删除某一类型的所有链接
    • 预览模式与确认模式
  5. 阻塞项分析：查找阻塞依赖关系
    • 某一问题的直接阻塞项
    • 递归遍历阻塞链
    • 循环依赖检测
    • 关键路径识别
  6. 依赖关系图：可视化关联关系
    • 导出为DOT格式（用于Graphviz）
    • 导出为Mermaid图
    • 导出为PlantUML格式
    • 导出为D2图（Terrastruct）
    • 传递依赖追踪
  7. 链接统计：分析链接模式
    • 单个问题或整个项目的统计数据
    • 按类型与方向分类的链接明细
    • 查找无链接的孤立问题
    • 识别关联最多的问题
    • 关联问题的状态分布
  8. 批量操作：一次性关联多个问题
    • 从JQL查询结果中关联
    • 进度跟踪
    • 跳过已存在的链接
  9. 克隆问题：复制带有关联关系的问题
    • 将字段复制到新问题
    • 与原问题创建“克隆”链接
    • 可选择复制子任务与链接

Available Commands

可用命令

CommandDescription
jira-as relationships link-types
List available link types
jira-as relationships link
Create link between issues
jira-as relationships get-links
View links for an issue
jira-as relationships unlink
Remove issue links
jira-as relationships get-blockers
Find blocker chain (recursive)
jira-as relationships get-dependencies
Find all dependencies
jira-as relationships stats
Analyze link statistics for issues/projects
jira-as relationships bulk-link
Bulk link multiple issues
jira-as relationships clone
Clone issue with links
All commands support 
--help
for full documentation.
命令描述
jira-as relationships link-types
列出可用的链接类型
jira-as relationships link
创建问题之间的链接
jira-as relationships get-links
查看某一问题的链接
jira-as relationships unlink
删除问题链接
jira-as relationships get-blockers
查找阻塞链（递归）
jira-as relationships get-dependencies
查找所有依赖关系
jira-as relationships stats
分析问题/项目的链接统计数据
jira-as relationships bulk-link
批量关联多个问题
jira-as relationships clone
克隆带有链接的问题
所有命令均支持
--help
查看完整文档。

Common Options

通用选项

All commands support these common options:
OptionDescription
-o/--output FORMAT
Output format (see table below)
--help
Show help message and exit
所有命令均支持以下通用选项：
选项描述
-o/--output FORMAT
输出格式（见下表）
--help
显示帮助信息并退出

Output Formats by Command

各命令支持的输出格式

CommandSupported Formats
link-types
text, json
link
text, json
get-links
text, json
unlink
text, json
get-blockers
text, json
get-dependencies
text, json, mermaid, dot, plantuml, d2
stats
text, json
bulk-link
text, json
clone
text, json
命令支持的格式
link-types
text, json
link
text, json
get-links
text, json
unlink
text, json
get-blockers
text, json
get-dependencies
text, json, mermaid, dot, plantuml, d2
stats
text, json
bulk-link
text, json
clone
text, json

Examples

示例

Quick Start - Common Operations

快速入门 - 常见操作

bash
undefined
bash
undefined

View available link types in your JIRA instance

查看JIRA实例中可用的链接类型

jira-as relationships link-types jira-as relationships link-types --filter block jira-as relationships link-types --output json
jira-as relationships link-types jira-as relationships link-types --filter block jira-as relationships link-types --output json

Create links using semantic flags

使用语义标记创建链接

jira-as relationships link PROJ-1 --blocks PROJ-2 jira-as relationships link PROJ-1 --is-blocked-by PROJ-2 # Inverse direction jira-as relationships link PROJ-1 --duplicates PROJ-2 jira-as relationships link PROJ-1 --clones PROJ-2 # Mark as clone jira-as relationships link PROJ-1 --relates-to PROJ-2 jira-as relationships link PROJ-1 --type "Blocks" --to PROJ-2
jira-as relationships link PROJ-1 --blocks PROJ-2 jira-as relationships link PROJ-1 --is-blocked-by PROJ-2 # 反向 jira-as relationships link PROJ-1 --duplicates PROJ-2 jira-as relationships link PROJ-1 --clones PROJ-2 # 标记为克隆 jira-as relationships link PROJ-1 --relates-to PROJ-2 jira-as relationships link PROJ-1 --type "Blocks" --to PROJ-2

View and remove links

查看并删除链接

jira-as relationships get-links PROJ-123 jira-as relationships get-links PROJ-123 --direction outward jira-as relationships unlink PROJ-1 PROJ-2 jira-as relationships unlink PROJ-1 PROJ-2 --dry-run jira-as relationships unlink PROJ-1 --type blocks --all
jira-as relationships get-links PROJ-123 jira-as relationships get-links PROJ-123 --direction outward jira-as relationships unlink PROJ-1 PROJ-2 jira-as relationships unlink PROJ-1 PROJ-2 --dry-run jira-as relationships unlink PROJ-1 --type blocks --all

Clone an issue with its relationships

克隆带有关联关系的问题

jira-as relationships clone PROJ-123 --clone-subtasks -l # -l is short for --clone-links jira-as relationships clone PROJ-123 -p OTHER # -p is short for --to-project jira-as relationships clone PROJ-123 --summary "Custom summary" jira-as relationships clone PROJ-123 --no-link # Skip creating "clones" link
undefined
jira-as relationships clone PROJ-123 --clone-subtasks -l # -l是--clone-links的缩写 jira-as relationships clone PROJ-123 -p OTHER # -p是--to-project的缩写 jira-as relationships clone PROJ-123 --summary "自定义摘要" jira-as relationships clone PROJ-123 --no-link # 跳过创建“克隆”链接
undefined

Advanced - Blocker Analysis & Statistics

进阶 - 阻塞项分析与统计

bash
undefined
bash
undefined

Find blocker chains for sprint planning

为迭代计划查找阻塞链

jira-as relationships get-blockers PROJ-123 --recursive jira-as relationships get-blockers PROJ-123 --recursive --include-done jira-as relationships get-blockers PROJ-123 -r --depth 3 # Limit recursion depth (0 = unlimited) jira-as relationships get-blockers PROJ-123 -r --depth 0 # Unlimited depth jira-as relationships get-blockers PROJ-123 -d inward # -d/--direction: inward or outward
jira-as relationships get-blockers PROJ-123 --recursive jira-as relationships get-blockers PROJ-123 --recursive --include-done jira-as relationships get-blockers PROJ-123 -r --depth 3 # 限制递归深度（0=无限制） jira-as relationships get-blockers PROJ-123 -r --depth 0 # 无限制深度 jira-as relationships get-blockers PROJ-123 -d inward # -d/--direction：内向或外向

Analyze dependencies (with link type filtering)

分析依赖关系（支持链接类型筛选）

jira-as relationships get-dependencies PROJ-123 jira-as relationships get-dependencies PROJ-123 -t blocks,relates # -t/--type for filtering
jira-as relationships get-dependencies PROJ-123 jira-as relationships get-dependencies PROJ-123 -t blocks,relates # -t/--type用于筛选

Link statistics - multiple modes

链接统计 - 多种模式

KEY_OR_PROJECT: optional positional argument for issue key or project key

KEY_OR_PROJECT：可选的位置参数，用于指定问题键或项目键

-p/--project: alternative option to specify project for project-wide analysis

-p/--project：指定项目进行全局分析的备选选项

jira-as relationships stats PROJ-123 # Single issue stats (positional arg) jira-as relationships stats PROJ # Project-wide stats (positional arg) jira-as relationships stats -p PROJ # Project-wide stats (-p/--project option) jira-as relationships stats --jql "type = Epic" # JQL-filtered stats jira-as relationships stats -p PROJ -t 20 # Show top 20 connected (-t/--top) jira-as relationships stats -p PROJ --max-results 100 # Limit issues analyzed
jira-as relationships stats PROJ-123 # 单个问题统计（位置参数） jira-as relationships stats PROJ # 项目全局统计（位置参数） jira-as relationships stats -p PROJ # 项目全局统计（-p/--project选项） jira-as relationships stats --jql "type = Epic" # JQL筛选后的统计 jira-as relationships stats -p PROJ -t 20 # 显示关联最多的前20个问题（-t/--top） jira-as relationships stats -p PROJ --max-results 100 # 限制分析的问题数量

Bulk link issues from JQL query (--output json for JSON output)

从JQL查询结果中批量关联问题（--output json输出JSON格式）

jira-as relationships bulk-link --jql "project=PROJ AND fixVersion=1.0" --relates-to PROJ-500 --dry-run jira-as relationships bulk-link --issues PROJ-1,PROJ-2,PROJ-3 --blocks PROJ-100 jira-as relationships bulk-link --issues PROJ-1,PROJ-2 --blocks PROJ-100 --output json jira-as relationships bulk-link --jql "sprint in openSprints()" --relates-to PROJ-500 --skip-existing # Skip already linked
undefined
jira-as relationships bulk-link --jql "project=PROJ AND fixVersion=1.0" --relates-to PROJ-500 --dry-run jira-as relationships bulk-link --issues PROJ-1,PROJ-2,PROJ-3 --blocks PROJ-100 jira-as relationships bulk-link --issues PROJ-1,PROJ-2 --blocks PROJ-100 --output json jira-as relationships bulk-link --jql "sprint in openSprints()" --relates-to PROJ-500 --skip-existing # 跳过已关联的问题
undefined

Visualization - Dependency Graphs

可视化 - 依赖关系图

bash
undefined
bash
undefined

Export for documentation (Mermaid for GitHub/GitLab)

导出用于文档（Mermaid适用于GitHub/GitLab）

jira-as relationships get-dependencies PROJ-123 --output mermaid
jira-as relationships get-dependencies PROJ-123 --output mermaid

Export for publication (Graphviz)

导出用于发布（Graphviz）

jira-as relationships get-dependencies PROJ-123 --output dot > deps.dot dot -Tpng deps.dot -o deps.png
jira-as relationships get-dependencies PROJ-123 --output dot > deps.dot dot -Tpng deps.dot -o deps.png

Export for PlantUML

导出为PlantUML格式

jira-as relationships get-dependencies PROJ-123 --output plantuml > deps.puml
jira-as relationships get-dependencies PROJ-123 --output plantuml > deps.puml

Export for D2/Terrastruct

导出为D2/Terrastruct格式

jira-as relationships get-dependencies PROJ-123 --output d2 > deps.d2 d2 deps.d2 deps.svg
undefined
jira-as relationships get-dependencies PROJ-123 --output d2 > deps.d2 d2 deps.d2 deps.svg
undefined

Exporting Dependency Graphs

导出依赖关系图

Use 
jira-as relationships get-dependencies
with 
--output
flag to generate diagrams:
  • Formats: 
    text
    (default), 
    json
    , 
    mermaid
    (GitHub docs), 
    dot
    (Graphviz), 
    plantuml
    , 
    d2
  • All formats include status-based coloring and link type labels
  • Run 
    jira-as relationships get-dependencies --help
    for rendering instructions
使用
jira-as relationships get-dependencies
并搭配
--output
标记生成图表：
  • 格式：
    text
    （默认）、
    json
    、
    mermaid
    （GitHub文档）、
    dot
    （Graphviz）、
    plantuml
    、
    d2
  • 所有格式均包含基于状态的颜色区分与链接类型标签
  • 运行
    jira-as relationships get-dependencies --help
    查看渲染说明

Link Types

链接类型

Standard JIRA link types and when to use them:
Link TypeOutwardInwardWhen to Use
Blocksblocksis blocked bySequential dependencies: Task A must finish before B starts
Duplicateduplicatesis duplicated byMark redundant issues; close the duplicate
Relatesrelates torelates toGeneral association; cross-team awareness
Clonersclonesis cloned byIssue templates; multi-platform variants
Link Direction: When A blocks B, A is "outward" (blocks) and B is "inward" (is blocked by). Use 
--blocks
when source issue blocks target; use 
--is-blocked-by
when source is blocked by target.
Note: Issue links are labels only - they do not enforce workflow rules. Combine with automation or team discipline.
标准JIRA链接类型及适用场景：
链接类型外向描述内向描述适用场景
Blocksblocksis blocked by顺序依赖：任务A必须在任务B开始前完成
Duplicateduplicatesis duplicated by标记冗余问题；关闭重复问题
Relatesrelates torelates to通用关联；跨团队同步
Clonersclonesis cloned by问题模板；多平台变体
链接方向：当A阻塞B时，A为“外向”（blocks），B为“内向”（is blocked by）。当源问题阻塞目标问题时使用
--blocks
；当源问题被目标问题阻塞时使用
--is-blocked-by
。
注意：问题链接仅为标签——不强制执行工作流规则。需结合自动化或团队规范使用。

Exit Codes

退出码

CodeDescription
0Success
1Error (validation failed, API error, or issue not found)
代码描述
0成功
1错误（验证失败、API错误或未找到问题）

Troubleshooting

故障排除

"Issue does not exist" error

“问题不存在”错误

  • Verify the issue key format is correct (e.g., PROJ-123)
  • Check that you have permission to view the issue
  • Confirm the project exists in your JIRA instance
  • 验证问题键格式是否正确（例如：PROJ-123）
  • 检查您是否有查看该问题的权限
  • 确认项目在您的JIRA实例中存在

"Link type not found" error

“未找到链接类型”错误

  • Run 
    jira-as relationships link-types
    to see available link types
  • Link type names are case-sensitive in some JIRA instances
  • Custom link types may have different names than standard ones
  • 运行
    jira-as relationships link-types
    查看可用的链接类型
  • 在部分JIRA实例中，链接类型名称区分大小写
  • 自定义链接类型的名称可能与标准类型不同

"Permission denied" when creating links

创建链接时“权限被拒绝”

  • Ensure you have "Link Issues" permission in the project
  • Some projects may restrict who can create certain link types
  • 确保您在项目中拥有“关联问题”权限
  • 部分项目可能限制某些用户创建特定类型的链接

Bulk link operations timing out

批量关联操作超时

  • Reduce the number of issues in a single operation
  • Use 
    --max-results
    to limit JQL query results
  • Consider breaking large operations into smaller batches
  • 减少单次操作的问题数量
  • 使用
    --max-results
    限制JQL查询结果
  • 考虑将大型操作拆分为多个小批次

Clone operation fails

克隆操作失败

  • Verify you have "Create Issues" permission in the target project
  • Check that required fields for the target project are satisfied
  • Some fields may not be cloneable (e.g., custom field restrictions)
  • 验证您在目标项目中拥有“创建问题”权限
  • 检查目标项目的必填字段是否已满足
  • 部分字段可能无法克隆（例如：自定义字段限制）

Circular dependency detected

检测到循环依赖

  • The blocker analysis command automatically detects and reports cycles
  • Review the blocker chain to identify and break the cycle
  • Consider whether the blocking relationship is correctly modeled
  • 阻塞项分析命令会自动检测并报告循环
  • 查看阻塞链以识别并打破循环
  • 考虑是否正确建模了阻塞关系

Configuration

配置

Requires JIRA credentials via environment variables (
JIRA_SITE_URL
, 
JIRA_EMAIL
, 
JIRA_API_TOKEN
).
需通过环境变量（
JIRA_SITE_URL
、
JIRA_EMAIL
、
JIRA_API_TOKEN
）提供JIRA凭证。

Architecture Patterns

架构模式

For strategic guidance on blocker chains, circular dependencies, cross-project linking, and visualization strategies, see Patterns Guide.
有关阻塞链、循环依赖、跨项目关联及可视化策略的战略指导，请参阅模式指南。

Related skills

相关Skill

  • jira-issue: For creating and updating issues
  • jira-lifecycle: For transitioning issues through workflows
  • jira-search: For finding issues to link
  • jira-agile: For epic and sprint management
  • jira-issue：用于创建与更新问题
  • jira-lifecycle：用于问题工作流转场
  • jira-search：用于查找待关联的问题
  • jira-agile：用于史诗与迭代管理