Jira Issue Relationships

jira-relationships

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

Risk Levels

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:

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
   • Remote (web) links to any URL via --remote-url
   • 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

Available Commands

All commands support --help for full documentation.

Common Options

Most commands support these common options:

Output Formats by Command

Note: link and unlink produce text output only - they do not accept -o/--output.

Examples

Quick Start - Common Operations

# 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

# Create a remote (web) link to any URL instead of a native issue link
jira-as relationships link PROJ-1 --remote-url https://example.com/runbook
jira-as relationships link PROJ-1 --remote-url https://example.com/spec --remote-title "Design spec" --remote-relationship "documented by"

# 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 MYAPP  # -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

# 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

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

Native Links vs Remote Links

Use a native link when both ends are JIRA issues, so get-links, get-blockers, and dependency graphs can traverse the relationship. Use --remote-url when the target is not a JIRA issue - a web page, documentation, or a JSM portal request view. --remote-title sets the display text (defaults to the URL) and --remote-relationship sets the relationship label shown on the issue.

Exit Codes

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