Bridging the Gap: GitHub's Missing Horizontal Issue Linking for Software Managers

The Missing Link: Horizontal Issue Relationships in GitHub

For many organizations migrating from GitLab to GitHub Enterprise Cloud, a critical feature gap often emerges: the absence of native 'horizontal' issue linking. Unlike GitLab's 'Linked items,' GitHub primarily offers 'vertical' relationships through sub-issues (parent-child), leaving cross-functional teams and software managers scrambling for effective ways to connect related, peer-level work items.

The discussion highlights a common pain point: managing complex projects across multiple repositories and teams requires more than just hierarchical issue structures. Teams need to easily visualize and track issues that are interdependent but not necessarily sub-tasks of one another. This 'horizontal' linking is vital for maintaining structured, comprehensible, and efficient documentation, which directly impacts the quality of developer reports and overall project visibility.

Why Current GitHub Workarounds Fall Short

Community members and migrating teams consistently find GitHub's current suggestions for related issues to be inadequate, especially at scale:

• Cross-referencing via Mentions (#123): While GitHub automatically creates a backlink in the timeline, this method lacks structure. It's a timeline event, easily missed in busy issues, and doesn't provide a dedicated, queryable 'Related Issues' section.
• Task Lists in a Tracking Issue: This can serve as a lightweight grouping mechanism, but it's entirely manual, prone to errors, and does not scale well for large projects or numerous related items. It also doesn't offer bidirectional linking.
• Project Custom Fields with Issue URLs: An 'ugly' solution, as described, involving text fields to store issue URLs. While potentially queryable if GitHub Projects are heavily utilized, it's cumbersome, lacks native integration, and doesn't offer the seamless experience of a dedicated feature.

These workarounds are not true bidirectional links and significantly increase the manual overhead for software managers and project leads trying to maintain clear project oversight and generate accurate developer reports.

Community Demand and Future Prospects

There's a strong, long-standing community demand for a native 'related issues' feature on GitHub. This functionality is seen as crucial for improving traceability, organization, and collaboration, particularly for large, cross-functional projects. The good news is that GitHub has been undergoing a broader issues overhaul, which includes recent additions like sub-issues, issue types, and custom fields. There's hope that horizontal linking could be introduced as part of this ongoing effort.

For organizations undertaking significant migrations, such as moving 40 repositories from GitLab, the lack of this feature presents a substantial challenge. Such concrete use cases, especially with a focus on how it impacts project management and the ability to use git analysis tools effectively, are valuable feedback for GitHub's product roadmap.

Recommendations for the Short Term

While awaiting a native solution, teams are advised to:

• Open a Feature Request: Submit a detailed feature request in the github/feedback repository, emphasizing the migration angle and the impact on project management and developer productivity.
• Implement a Structured Workaround: For immediate needs, the least painful option involves consistently using cross-references (#123) combined with a dedicated 'Related Issues' section at the top of each issue body. This provides a manual, but visible, grouping of related items.

### Related Issues

- #123 (Dependency)
- #456 (Related Feature)
- #789 (Blocked by)

Implementing a consistent approach, even with workarounds, can help teams maintain some level of clarity and facilitate better developer reports during the transition period, until GitHub introduces a more robust, native solution for horizontal issue linking.