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

All commands support these common options:

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

# Clone an issue with its relationships
jira-as relationships clone PROJ-123 --clone-subtasks --clone-links
jira-as relationships clone PROJ-123 --to-project OTHER
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

# Analyze dependencies (with link type filtering)
jira-as relationships get-dependencies PROJ-123
jira-as relationships get-dependencies PROJ-123 --type blocks,relates

# Link statistics - multiple modes
jira-as relationships stats PROJ-123                       # Single issue stats
jira-as relationships stats --project PROJ                 # Project-wide stats
jira-as relationships stats --jql "type = Epic"            # JQL-filtered stats
jira-as relationships stats --project PROJ --top 20        # Show top 20 connected

# Bulk link issues from JQL query
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

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.

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