jira-relationships

Issue linking and dependency management for JIRA - create, view, and analyze issue relationships.

Risk Levels

Operation	Risk	Notes
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

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

What this skill does

IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.

This skill provides issue relationship operations:

•
Get Link Types: View available link types in JIRA instance
- •Lists all configured link types
- •Shows inward/outward descriptions
- •Filter by name pattern
•
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
•
View Links: See all relationships for an issue
- •Filter by direction (inward/outward)
- •Filter by link type
- •Shows linked issue status and summary
•
Remove Links: Delete issue relationships
- •Remove specific links between issues
- •Remove all links of a type
- •Dry-run and confirmation modes
•
Blocker Analysis: Find blocking dependencies
- •Direct blockers for an issue
- •Recursive blocker chain traversal
- •Circular dependency detection
- •Critical path identification
•
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
•
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
•
Bulk Operations: Link multiple issues at once
- •Link from JQL query results
- •Progress tracking
- •Skip existing links
•
Clone Issues: Duplicate issues with relationships
- •Copy fields to new issue
- •Create "clones" link to original
- •Optionally copy subtasks and links

Available Commands

Command	Description
`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.

Common Options

All commands support these common options:

Option	Description
`-o/--output FORMAT`	Output format (see table below)
`--help`	Show help message and exit

Output Formats by Command

Command	Supported 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

Examples

Quick Start - Common Operations

bash

# View available link types in your JIRA instance
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

# 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

# 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

Advanced - Blocker Analysis & Statistics

bash

# 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

# 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

# Link statistics - multiple modes
# KEY_OR_PROJECT: optional positional argument for issue key or project key
# -p/--project: alternative option to specify project for project-wide analysis
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

# Bulk link issues from JQL query (--output json for JSON output)
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

Visualization - Dependency Graphs

bash

# Export for documentation (Mermaid for GitHub/GitLab)
jira-as relationships get-dependencies PROJ-123 --output mermaid

# Export for publication (Graphviz)
jira-as relationships get-dependencies PROJ-123 --output dot > deps.dot
dot -Tpng deps.dot -o deps.png

# Export for PlantUML
jira-as relationships get-dependencies PROJ-123 --output plantuml > deps.puml

# Export for D2/Terrastruct
jira-as relationships get-dependencies PROJ-123 --output d2 > deps.d2
d2 deps.d2 deps.svg

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

Link Types

Standard JIRA link types and when to use them:

Link Type	Outward	Inward	When to Use
Blocks	blocks	is blocked by	Sequential dependencies: Task A must finish before B starts
Duplicate	duplicates	is duplicated by	Mark redundant issues; close the duplicate
Relates	relates to	relates to	General association; cross-team awareness
Cloners	clones	is cloned by	Issue 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.

Exit Codes

Code	Description
0	Success
1	Error (validation failed, API error, or issue not found)

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

"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

"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

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).

Architecture Patterns

For strategic guidance on blocker chains, circular dependencies, cross-project linking, and visualization strategies, see Patterns Guide.

Related skills

•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