PR Link Rate Report

Overview

The PR Link Rate measures what percentage of your merged pull requests are linked to issues in your project management system. This metric helps you maintain traceability between code changes and the work they're meant to accomplish, ensuring better visibility and documentation of your development process.

At a glance:

• What it measures: Percentage of merged PRs that are linked to at least one issue

• Why it matters: Ensures code changes are traceable to planned work and business requirements

• Metric type: Process health indicator (higher is better)

• Format: Percentage (e.g., 85%)

How It's Calculated

PR Link Rate = (Merged PRs with Linked Issues / Total Merged PRs) × 100%

Components:

• Merged PRs with Linked Issues: Count of merged pull requests that have at least one associated issue

• Total Merged PRs: Count of all merged pull requests

What counts as "linked": A PR is considered linked when it references at least one issue from your project management system (Jira, Linear, GitHub Issues, Azure DevOps, etc.). This typically happens through:

• PR descriptions mentioning issue IDs (e.g., "Fixes #123")

• Branch names containing issue references

• Commit messages with issue links

• Manual linking in your VCS platform

Important notes:

• Only merged PRs are included in the calculation

• Only development contributors are counted (excludes bots, non-engineers)

• A PR only needs to link to one issue to count as "linked" (multiple links don't change the count)

Why PR Link Rate Matters

The Problem with Unlinked PRs

When PRs aren't linked to issues, you lose critical visibility:

❌ No work traceability: Can't connect code changes back to requirements or user stories
❌ Poor code review context: Reviewers don't understand the "why" behind changes
❌ Incomplete documentation: Historical record doesn't show what work was done
❌ Broken workflow visibility: Can't track issue progress through to code completion
❌ Audit and compliance gaps: Can't prove which code addresses which requirements
❌ Planning disconnects: Work happens that wasn't planned or tracked

The Benefits of High Link Rates

When PRs are consistently linked to issues, you gain:

✅ Complete traceability: Every code change traces back to a business need or requirement
✅ Better code reviews: Reviewers can click through to see the full context, requirements, and acceptance criteria
✅ Accurate velocity tracking: Issue completion automatically reflects when code is merged
✅ Improved planning: See how much planned work translates to code changes
✅ Audit readiness: Compliance requirements to show what code addresses which requirements
✅ Historical clarity: Future developers can understand why code was written
✅ Stakeholder visibility: Product managers and leadership can see work progress through to code

Finding the Report

Navigation:

1. Go to Productivity in the main sidebar

2. Select Issue Tracking category

3. Find the PR Link Rate metric

Requirements:

• Version control system integration (GitHub, GitLab, Azure DevOps, Bitbucket)

• Project management system integration (Jira, Linear, GitHub Issues, Azure DevOps, etc.)

The metric appears alongside other issue tracking metrics like:

• Issue Completion Rate

• Issues Completed Per Week

• Issue Cycle Time

Available Filters & Customization

Automatic Filters Applied

The metric automatically:

• Includes: Only merged PRs (excludes open or closed-without-merge)

• Includes: Only development contributors (excludes bots and service accounts)

• Compares: Against percentile benchmarks from peer organizations

Breakdown Options

Analyze PR link rate by:

• Individual contributors: See who consistently links PRs vs. who doesn't

• Teams/groups: Compare linking discipline across teams

• Repositories: Identify repos with poor linking practices

• Time periods: Track trends over weeks, months, or quarters

Asset-Level Drill-Down

Click through to see:

• Linked PRs: List of PRs with associated issues

• Unlinked PRs: List of PRs missing issue links (candidates for improvement)

• Issue details: What issues are linked to each PR

Key Use Cases

1. Enforcing Work Traceability

Ensure every code change connects to tracked work:

Use case: Your organization requires traceability for compliance (SOC 2, ISO 27001, regulatory requirements)

How PR Link Rate helps:

• Monitor organization-wide linking discipline

• Identify teams or individuals who need training

• Track improvement over time after implementing policies

• Provide audit evidence of work tracking practices

Action: Set a target link rate (e.g., 90%+) and monitor compliance

2. Improving Code Review Quality

Give reviewers the context they need:

Without links:

• Reviewer: "Why are we making this change?"

• Author: "It's for the authentication refactor"

• Reviewer: "What are the requirements?"

• Author: Searches for issue link to paste in comments

With links:

• Reviewer clicks issue link in PR description

• Sees full context, acceptance criteria, designs, and discussion

• Reviews code with complete understanding

• Faster, higher-quality reviews

Action: Track link rate by team and correlate with review cycle time

3. Connecting Planning to Execution

Close the loop between issue tracking and code delivery:

Use case: Product managers want to know when planned features are actually coded

How PR Link Rate helps:

• High link rate means issues automatically update when code merges

• Product managers can trust issue status as source of truth

• No disconnect between "ticket says done" and "code is merged"

• Roadmap tracking reflects actual engineering progress

Action: Report link rate to product/planning teams to build trust in issue tracking

4. Identifying Process Gaps

Find where work isn't being properly tracked:

Low link rate signals:

• Urgent hotfixes bypassing normal planning

• Technical debt work not captured in issue tracker

• Engineering work that isn't visible to product/leadership

• Poor developer onboarding (new hires not following practices)

Action: Investigate unlinked PRs to understand what work isn't being tracked and why

5. Supporting Issue Lifecycle Metrics

Enable accurate issue tracking metrics:

Metrics that depend on PR links:

• Issue Cycle Time: When did work actually complete?

• Issue Throughput: How many planned issues turned into code?

• Work in Progress: Are issues "in progress" because PRs aren't linked?

Without PR links: Issue metrics become unreliable because issue status doesn't reflect actual code work

Action: Maintain high link rate (>85%) to ensure issue metrics are accurate

6. Measuring Team Maturity

Assess engineering process discipline:

Link rate as maturity indicator:

• <50%: Ad-hoc processes, poor tracking discipline

• 50-70%: Developing processes, inconsistent follow-through

• 70-85%: Mature processes, most work tracked properly

• >85%: Highly disciplined team, excellent traceability

Action: Use link rate as a key process health metric in team assessments

Related Metrics

Combine PR Link Rate with these metrics for deeper insights:

Interpreting Your Results

Healthy Patterns ✅

High and stable link rate (>85%) indicates:

• Strong engineering discipline

• Well-established processes

• Good developer onboarding

• Reliable issue tracking data

• Effective traceability for compliance

Indicates: Mature team with excellent work tracking practices

Warning Signs ⚠

Low link rate (<70%) may indicate:

• Process gaps: Work happening outside normal planning

• Poor enforcement: Policy exists but isn't followed

• Training issues: Developers don't know how to link PRs

• Tool problems: Linking mechanism is difficult or broken

• Culture issues: Team doesn't value traceability

Declining link rate (trending downward) signals:

• Process discipline degrading

• Team growing without proper onboarding

• Increased urgent/unplanned work

• Burnout or corner-cutting under pressure

Very high link rate (>95%) with low productivity may indicate:

• Process bureaucracy slowing teams down

• Engineers creating unnecessary issues just to link PRs

• Over-emphasis on metrics vs. outcomes

Span's Automated Signal: Low PR Link Rate

Span automatically monitors your PR link rate and generates a "Low PR Link Rate" signal when linking discipline degrades significantly.

How the signal works:

• Compares: Recent 2-week link rate vs. historical 8-week baseline

• Triggers: When recent rate is 30% lower than historical average

• Purpose: Alert teams to investigate why linking discipline has degraded

Example:

• Historical baseline: 80% link rate

• Recent 2 weeks: 55% link rate

• Drop: 31% decline → Signal generated

When you receive this signal:

1. Review recent unlinked PRs to identify patterns

2. Check if urgent work is bypassing normal processes

3. Verify team members understand linking practices

4. Investigate tool or integration issues

5. Address with team in retrospective

Best Practices

For Individual Contributors

1. Link PRs in the description: Include issue references in PR description (e.g., "Closes #123")

2. Use branch naming conventions: Include issue ID in branch name (e.g., feature/ABC-123-auth-refactor)

3. Check before submitting: Verify link appears before requesting review

4. Link to primary issue: If work touches multiple issues, link to the main one at minimum

5. Create issues retroactively: If you forgot to create an issue, create one before merging and link it

For Team Leads

1. Set clear expectations: Make PR linking a standard part of your team's definition of done

2. Include in code review: Reviewers should check for issue links before approving

3. Monitor the metric: Review link rate weekly to catch degradation early

4. Investigate outliers: Talk to developers with consistently low link rates

5. Automate reminders: Use PR templates or bots to remind about linking

6. Celebrate improvement: Recognize teams that improve linking discipline

For Engineering Managers

1. Set organizational targets: Aim for 85%+ link rate across all teams

2. Track in working norms: Add PR Link Rate to your team's working norms with target thresholds

3. Compare across teams: Identify teams that need support or training

4. Correlate with other metrics: Check if low link rate correlates with other process issues

5. Review unplanned work: Low link rates may reveal urgent work not captured in planning

6. Include in onboarding: Train new hires on linking practices from day one

For Organizations

1. Implement automation: Use GitHub Actions, GitLab CI, or Azure Pipelines to:

   • Check for issue links before allowing merge

   • Auto-link based on branch names

   • Post comments reminding about links

2. Standardize branch naming: Require issue IDs in branch names (e.g., ABC-123-description)

3. Use PR templates: Include issue link section in PR templates

4. Enable integrations: Ensure VCS and project management tools are properly integrated

5. Make it easy: Reduce friction in the linking process

6. Audit for compliance: Use high link rate as evidence of development traceability

Common Automation Patterns

GitHub Example: Require Issue Links

# .github/workflows/check-pr-link.yml
name: Check PR Link
on: pull_request

jobs:
  check-link:
    runs-on: ubuntu-latest
    steps:
      - name: Check for issue link
        uses: actions/github-script@v6
        with:
          script: |
            const body = context.payload.pull_request.body || '';
            const hasLink = /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#\d+/i.test(body);
            
            if (!hasLink) {
              core.setFailed('PR must link to an issue. Use "Closes #123" in description.');
            }

Branch Naming Convention

Pattern: <type>/<issue-id>-<description>

Examples:

• feature/JIRA-123-user-authentication

• bugfix/GH-456-fix-login-error

• hotfix/LIN-789-critical-security-patch

Benefit: Many tools auto-link PRs to issues when branch names include issue IDs

Common Questions

Q: What's a "good" PR link rate?
A: Aim for 85%+ for mature teams. Rates above 90% indicate excellent discipline. Below 70% suggests process gaps that need attention. Use Span's percentile benchmarks to see how you compare to peer organizations.

Q: Should 100% of PRs be linked?
A: Not necessarily. Some legitimate exceptions include:

• Documentation-only changes

• Dependency updates (though you may want issues for these)

• Minor typo fixes

• Emergency hotfixes (though create issues retroactively)

Target 90-95% rather than 100% to allow for reasonable exceptions.

Q: Does linking to multiple issues help?
A: For the metric: No—a PR with 1 link vs. 5 links both count as "linked."
For traceability: Yes—link to all relevant issues for better context and tracking.

Q: What if we have urgent work that bypasses planning?
A: Create issues retroactively! Even for hotfixes, create an issue describing the problem and link the PR before merging. This maintains traceability and helps with post-incident reviews.

Q: Our link rate is 95% but issue tracking still feels broken. Why?
A: High link rate measures that links exist, not that they're correct or meaningful. Check:

• Are links to the right issues?

• Are issue descriptions clear and complete?

• Are issues updated when PRs merge?

• Is work being split across too many small issues?

Q: Can we enforce 100% link rate with automation?
A: Yes, technically—but consider allowing approved exceptions for docs, minor fixes, etc. Overly rigid enforcement can create busywork (creating trivial issues just to link).

Q: How do we improve a low link rate?
A: Multi-pronged approach:

1. Education: Ensure everyone knows how and why to link

2. Automation: Use PR templates and CI checks

3. Process: Include link checking in code review

4. Culture: Make traceability a team value

5. Tools: Ensure linking is easy and clear

Q: Does this work with all VCS and issue tracking tools?
A: Yes, Span supports:

• VCS: GitHub, GitLab, Azure DevOps, Bitbucket

• Issue Tracking: Jira, Linear, GitHub Issues, Azure DevOps Boards

The linking mechanism depends on your specific tool combination—check your integration documentation.

Q: What if developers forget to link PRs?
A: Options:

• Prevention: PR templates with link section, branch naming requirements

• Detection: CI/CD checks that fail without links

• Correction: Review unlinked PRs and add links before merging

• Retroactive: Link PRs to issues after the fact (less ideal but better than nothing)

Troubleshooting

"Link rate seems too low"

Check:

• ✓ Are integrations properly configured between VCS and issue tracking?

• ✓ Do developers know how to link PRs in your specific tools?

• ✓ Are PR templates being used?

• ✓ Is the linking syntax correct for your tools?

Action:

• Review recent unlinked PRs to identify patterns

• Survey team about barriers to linking

• Verify integration is detecting links correctly

"Link rate dropped suddenly"

Check:

• ✓ Did you have an incident or urgent release requiring hotfixes?

• ✓ Did new team members join without proper onboarding?

• ✓ Did integration break or change?

• ✓ Is there increased unplanned work?

Action:

• Investigate via Span's "Low PR Link Rate" signal details

• Review recent unlinked PRs

• Check with team about process changes or pressures

"Link rate is high but metrics still feel wrong"

Problem: Links exist but may not be meaningful

Check:

• ✓ Are PRs linking to generic "miscellaneous" issues?

• ✓ Are links accurate (right PR to right issue)?

• ✓ Are issues being reused incorrectly?

• ✓ Are issue descriptions clear and complete?

Action: Audit link quality, not just quantity—review a sample of linked PRs

"Tools aren't detecting links"

Common causes:

• Incorrect linking syntax for your tool combination

• Integration not properly configured

• Permissions issues preventing Span from seeing issue associations

• PRs linked after merge (some integrations only check at merge time)

Action:

• Review integration documentation for correct syntax

• Test with a sample PR to verify detection

• Check integration health in Span settings

Getting Started

Step 1: Check Your Baseline

Review your current PR link rate in Span. Understand where you're starting from.

Step 2: Set a Target

Based on your baseline and team maturity:

• Starting point (<50%): Target 70% within 3 months

• Developing (50-70%): Target 85% within 3 months

• Mature (70-85%): Target 90%+ within 3 months

• Excellent (>85%): Maintain and investigate any drops

Step 3: Identify Quick Wins

Look at unlinked PRs from the last month:

• Which repos have the lowest link rate?

• Which team members need training?

• Are there common patterns (hotfixes, docs, etc.)?

Step 4: Implement Process Changes

• Add PR linking to your team's definition of done

• Update PR templates to include issue link section

• Train team on proper linking syntax

• Add link checking to code review checklist

Step 5: Consider Automation

• Implement CI checks for issue links

• Use branch naming conventions with issue IDs

• Set up bots to remind about missing links

Step 6: Monitor and Iterate

• Review link rate weekly

• Investigate any drops >10%

• Celebrate improvements

• Share best practices across teams

Step 7: Enable Span Signals

Add PR Link Rate to your team's working norms to receive automated alerts when linking discipline degrades.

Working Norms Integration

Span supports PR Link Rate as a configurable working norm that your team can track and monitor.

What this enables:

• Set target link rate thresholds for your team

• Track 7-day rolling averages

• Receive notifications when link rate drops below targets

• Monitor trends over time

• Compare against organizational standards

How to set up:

1. Go to Working Norms in Span

2. Add PR Link Rate norm

3. Set your target threshold (e.g., 85%)

4. Configure alert preferences

5. Review in team meetings

Category: Project Tracking
Purpose: Maintain traceability between code changes and tracked work

Impact on Other Metrics

High PR link rate improves the accuracy and reliability of:

Bottom line: PR Link Rate is a foundational metric that enables accurate tracking across your entire engineering organization.

Need Help?

If you have questions about improving your PR Link Rate or want guidance on implementing linking practices and automation, reach out to your Span customer success manager.