PR Link Rate Report

Overview

The PR Link Rate measures the percentage of merged pull requests that are linked to issues in your project management system. This metric provides visibility into work traceability and process discipline, helping you understand how well your code changes are connected to tracked work items.

Formula: (Merged PRs with Linked Issues ÷ Total Merged PRs) × 100

This is classified as a positive metric - higher percentages indicate better traceability and process discipline.

What This Report Shows

Primary Metric:

• PR Link Rate - Percentage of merged PRs linked to at least one issue

Supporting Data:

• Total merged PRs with linked issues (count)

• Total merged PRs (count)

• Percentile rank comparison to other organizations

• Historical trend analysis

How to Access This Report

1. Navigate to Insights → Productivity > Velocity category

2. Issue Lifecycle tab, locate the "PR Link Rate" metric card

3. View:

   • Current percentage value with percentile rank

   • Time-series trend visualization

   • Breakdown by person, team, or repository

Related Metrics in Issue Tracking:

• Issues Completed Per Active Coding Day

• Done Issues Percentage

• Issue Cycle Time

• Issue Lifetime

How the Metric is Calculated

What Counts as "Linked"

A PR is counted as linked when:

• ✅ The PR is in merged status

• ✅ The PR has at least one linked issue in your project management system

• ✅ The link exists in your PM system at merge time

What Does NOT Count

❌ Open, draft, or closed (unmerged) PRs
❌ PRs without any issue reference in the PM system
❌ Reverted PRs

Supported Issue Tracking Systems

Span detects links from:

• Jira

• Linear

• Azure DevOps (coming soon)

How Links Are Detected

Links are detected by reading issue linking data from your integrated project management system. Span ingests the PR-to-issue relationships as they are recorded natively in your issue tracker.

📋 Critical Requirement: A project management integration must be enabled for this metric to function.

Key Insights from This Report

Work Traceability

• High link rates (70-100%) → Strong traceability; code changes connected to documented requirements

• Low link rates (<50%) → Work being deployed without tracked requirements or documentation

• Shows how well you can trace production changes back to business needs

Process Discipline

• Monitor consistency of linking practices across teams

• Identify individuals or teams who may need coaching

• Track improvements in development process maturity

Quality & Compliance

• Better traceability supports:

  • Audit requirements

  • Impact analysis when issues arise

  • Release note generation

  • Change management processes

• Critical for regulated industries (finance, healthcare, government)

Development Velocity Context

• Understand what portion of your delivery is tracked work

• Identify unplanned work entering the system

• Support capacity planning and forecasting

Automated Monitoring: Low PR Link Rate Alert

Span automatically detects when your linking discipline degrades:

How It Works:

• Comparison Window: Recent 2 weeks vs. historical 8-week average

• Alert Threshold: Triggered when recent rate drops 30% or more below baseline

• Scope: Generated at team/group level

Example:

• Historical average: 80% link rate

• Recent 2 weeks: 55% link rate

• Drop: 31% → Alert triggered ⚠

This helps catch process degradation early without requiring manual monitoring.

Interpreting the Data

Understanding the Percentage

Percentile Rankings

• Higher percentile = Better traceability compared to peers

• Use to set realistic targets based on industry benchmarks

• Compare against organizations with similar development practices

Trend Analysis

Viewing Unlinked PRs

Finding PRs Without Links

1. Navigate to Organization → Catalog → Pull Requests

2. Filter to show only merged PRs

3. Look for the "Linked Issues" column:

   • Displays clickable issue links when present

   • Shows "N/A" when no issues are linked

4. Sort or filter by this column to identify unlinked PRs

Analyzing Patterns

Use filters to understand:

• Which developers have lower link rates

• Which repositories have more unlinked PRs

• Which time periods show degraded linking

• Specific PRs that were merged without links

This enables targeted coaching and process improvement.

Common Reasons for Unlinked PRs

While Span doesn't automatically categorize unlinked PRs, common legitimate scenarios include:

Often Legitimately Unlinked

• 🚨 Emergency hotfixes - Urgent production fixes

• 🤖 Dependency updates - Automated bot updates (Dependabot, Renovate)

• 📚 Documentation changes - README, docs-only updates

• 🔧 Infrastructure/DevOps - CI/CD, build system changes

• ♻ Code refactoring - Technical cleanup without feature changes

• ⚙ Configuration changes - Environment or settings updates

Should Be Linked

• ✨ Feature development - New capabilities or enhancements

• 🐛 Bug fixes - Addressing reported issues

• 🔐 Security patches - Vulnerability fixes

• 📊 Performance improvements - Optimization work

• 💥 Breaking changes - API or interface modifications

Best Practice Recommendation

Define an organizational policy on:

• Which PR types require issue links

• How to handle emergency/unplanned work

• Whether to retroactively link PRs

• Acceptable exceptions and how to document them

Best Practices for Improving PR Link Rate

Process Automation

1. PR Templates

• Include issue link section in PR description template

• Make issue reference a required field

• Provide examples and formatting guidance

2. Branch Naming Conventions

• Use issue keys in branch names (e.g., feature/PROJ-123-add-login)

• Configure automatic link detection from branch names

• Enforce naming through CI/CD checks

3. CI/CD Checks

• Add checks that fail if PR has no linked issue

• Allow override for documented exceptions

• Provide clear error messages with linking instructions

4. Bot Automation

• Configure bots to auto-link based on branch names or commit messages

• Use automation tools that integrate with your PM system

• Mark automation accounts properly in Span to exclude them

Team Practices

1. Developer Training

• Educate team on why linking matters

• Show how to link PRs in your specific tools

• Share impact on traceability and compliance

2. Code Review Standards

• Include issue link verification in review checklist

• Reviewers should confirm link before approval

• Document exceptions when legitimate

3. Regular Monitoring

• Review PR Link Rate in team meetings

• Celebrate improvements

• Investigate sudden drops immediately

4. Establish Clear Policy

• Document when linking is required vs. optional

• Define how to handle emergency work

• Create process for retroactive linking if needed

Related Metrics to Review Together

Issue Tracking Metrics

• Issues Completed Per Active Coding Day - Throughput of tracked work

• Issue Cycle Time - How long issues take to complete

• Done Issues Percentage - Completion rate of tracked work

Delivery Metrics

• PRs Merged Per Week - Volume context for link rate

• Total Merged PRs - Overall delivery pace

• % PRs Merged Without Review - Combined with low link rate = high risk

Combined Analysis Examples

High Risk Combination:

• Low PR Link Rate + High % without review + Low % with tests = Critical quality/traceability issue

Process Maturity:

• High PR Link Rate + Low issue cycle time + High completion rate = Mature, efficient process

Unplanned Work Signal:

• Decreasing PR Link Rate + Increasing PR volume = Growing unplanned/untracked work

Configuration & Requirements

Integration Requirements

Required:

• ✅ Version Control System integration (GitHub, GitLab, Azure DevOps)

Strongly Recommended:

• ✅ Project Management integration (Jira, Linear, GitHub Issues, Azure DevOps)

Without PM integration, link detection capabilities will be limited.

Span Configuration

Bot Account Setup:

• Mark automation accounts (Dependabot, Renovate) as bots

• Bot-authored PRs can be excluded from analysis

• Location: Organization Settings → Bot Accounts

Permission Model:

• Metric respects organization's team/project permissions

• Users see data based on their access level

VCS Platform Settings

Branch Protection Rules:

• Can require issue references in PR descriptions

• Enforce through status checks

• Prevent merge without links

PR Templates:

• Configure in your VCS repository settings

• Include dedicated section for issue links

• Provide clear instructions

Edge Cases & Limitations

Multi-Repository Scenarios

• Metric aggregates across all repositories in organization

• Can filter results by specific repository

• No special handling for cross-repo dependencies

Monorepo Considerations

• Standard calculation applies

• No special adjustments for monorepo patterns

• May want to segment by code ownership areas

Issue Type Handling

• Metric counts ANY linked issue type equally:

  • Bugs

  • Stories

  • Tasks

  • Subtasks

• Does not distinguish between issue types in the percentage

• Use additional filtering if type-specific analysis needed

Timing Considerations

• Link status evaluated at merge time

• Retroactive linking won't change historical metrics

• Future calculations will reflect new links

Troubleshooting Common Issues

"My PRs are linked but not showing in the metric"

Possible causes:

• Link created after PR was merged

• PR status is not "merged"

• PM integration not properly configured

• Link exists in different PM system than integrated

Solutions:

• Verify PM integration is active and syncing

• Check that links are created before merge

• Confirm PR is in merged status

"Automated PRs are inflating my percentage"

Solutions:

• Mark automation accounts as bots in Span settings

• Configure whether bot PRs should be included/excluded

• Set up separate tracking for automated vs. manual PRs

"We link in commits but not PR descriptions"

Note: Link detection varies by PM system

• Some systems detect links from commit messages

• Others require explicit PR-issue links

• Check your PM system's documentation for linking methods

• Configure your VCS to sync commit-based links to PR metadata

"Our emergency hotfixes are lowering the metric"

Approaches:

• Create issues retroactively for hotfixes

• Establish "emergency" issue type for rapid linking

• Document exceptions with clear policy

• Use tagging to distinguish emergency vs. planned work

Quick Reference by Role

Getting Started Checklist

Prerequisites:

•  Version Control System integration enabled

•  Project Management integration enabled

Setup:

•  Establish baseline PR Link Rate for your org

•  Define organizational linking policy

•  Set up PR templates with issue link sections

•  Configure branch naming conventions

•  Enable Low PR Link Rate alerts

Ongoing:

•  Review metric weekly/monthly with teams

•  Investigate drops immediately

•  Celebrate improvements

•  Refine policy based on learnings

•  Share best practices across teams

Summary

The PR Link Rate metric provides critical visibility into work traceability and process discipline. By maintaining high link rates, you ensure:

• ✅ Better traceability from code changes to business requirements

• ✅ Improved audit and compliance capabilities

• ✅ Enhanced impact analysis when issues arise

• ✅ Stronger development process maturity

• ✅ Better visibility into planned vs. unplanned work

Key Takeaways:

• Higher percentages = Better traceability

• Use automated alerts to catch degradation early

• Combine with quality metrics for complete picture

• Establish clear policy on when linking is required

• Use PR templates and automation to make linking easy

• Monitor trends, not just point-in-time values

Need Help?

• Contact your Span customer success team for guidance

• Visit the Help Center for integration documentation

• Share best practices with your Span community