Footer with Issue References
How to add footer references in Conventional Commits. Learn the key: value and key #value footer formats for linking issues, reviewers, and metadata.
Detailed Explanation
Footer Format in Conventional Commits
Footers appear after the commit body (or after the subject if there is no body), separated by a blank line. They follow one of two formats:
Format 1: key: value
Reviewed-by: Alice Smith
Refs: https://jira.example.com/PROJ-123
Signed-off-by: Bob <bob@example.com>
Format 2: key #value
Closes #456
Fixes #789
Refs #123
Complete Example
feat(notifications): add email digest for weekly summary
Users can now opt in to receive a weekly email digest
summarizing their activity. The digest includes new
followers, likes, and comment replies.
Closes #234
Refs #180, #201
Reviewed-by: Carol
Co-authored-by: Dave <dave@example.com>
Common Footer Tokens
| Token | Purpose | Example |
|---|---|---|
Closes |
Close an issue on merge | Closes #123 |
Fixes |
Fix an issue on merge | Fixes #456 |
Refs |
Reference related issues | Refs #789 |
Reviewed-by |
Credit a reviewer | Reviewed-by: Alice |
Co-authored-by |
Credit a co-author | Co-authored-by: Bob <b@x.com> |
Signed-off-by |
DCO sign-off | Signed-off-by: Carol <c@x.com> |
BREAKING CHANGE |
Breaking change description | See dedicated example |
GitHub Auto-Close Keywords
GitHub recognizes these tokens and automatically closes the referenced issue when the commit is merged to the default branch: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved.
Validation
The linter checks that footer lines match either the key: value or key #value format. Lines that do not match either pattern are flagged as warnings, since they may be continuation lines of a multi-line footer value.
Use Case
Use footer references to link commits to issue trackers, credit reviewers and co-authors, and add metadata like sign-offs. This creates a traceable connection between commits and the issues they address, which is invaluable for project management and audit trails.