Referencing Issues and Tickets
You'll learn how linking commits to issue trackers creates a paper trail that connects code changes to their business context.
The Core Idea
When you write a commit message, you can include a reference to an issue number or ticket ID from your project management system (like GitHub Issues, Jira, or Linear). This creates a bidirectional link: the commit points to the issue explaining why the work was done, and the issue tracker shows which commits addressed that problem.
Think of it like citing sources in a research paper. Your commit is the claim; the issue ticket is your supporting evidence and context. Anyone reviewing the code later can trace back to the original requirement, bug report, or feature request.
Common Conventions
Most teams follow simple patterns:
- End of subject line:
Fix login validation (#42) - In the body:
Closes #123orFixes #456 - Multiple issues:
Relates to #78, partially addresses #90
Many platforms automatically detect these patterns. For example, writing Closes #42 in a GitHub commit message will automatically close issue #42 when that commit merges to the main branch.
Why This Matters
Referencing issues connects your technical history (commits) with your project history (requirements and decisions). When someone asks "Why does the code work this way?" they can follow the breadcrumb trail from commit → issue → discussion → original decision. This is invaluable for onboarding new team members, debugging mysterious behaviors, or auditing compliance requirements.
Key Takeaway:
Always reference relevant issue numbers in your commit messages to create traceability between code changes and the business context that motivated them.