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) | | Create remote link | - | Adds a web link to the issue | | 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
- Remote (web) links to any URL via --remote-url
- 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, or a remote (web) link to a URL | | 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

Most commands support these common options:

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

Output Formats by Command

| Command | Supported Formats | |---------|-------------------| | link-types | text, json | | get-links | text, json | | get-blockers | text, json | | get-dependencies | text, json, mermaid, dot, plantuml, d2 | | stats | text, json | | bulk-link | text, json | | clone | text, json |

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

Native Links vs Remote Links

| | Native issue link | Remote (web) link | |---|-------------------|-------------------| | Target | Another JIRA issue | Any URL (docs, wikis, JSM portal views, external trackers) | | Flags | --blocks, --relates-to, ..., or --type + --to | --remote-url (+ optional --remote-title, --remote-relationship) | | Typed and directional | Yes (see link types above) | No - free-form relationship text (e.g., "documented by") | | Traversable by blocker/dependency analysis | Yes | No |

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

| 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