Mentions & References
GitHub turns ordinary markdown into a hyperlinked web of people, issues, PRs, and commits. Drop @alice and it becomes a notification; type #142 and it becomes a link to issue 142. Once you internalise the syntax, you can wire up a project’s history just by typing.
The reference syntax at a glance
Syntax | What it does | Example |
|---|---|---|
@username | Mention and notify a person | @alice |
@org/team | Mention and notify a team | @acme-co/frontend |
#123 | Link issue or PR in same repo | #142 |
GH-123 | Same as #123 (legacy) | GH-142 |
org/repo#123 | Cross-repo issue or PR | acme-co/design#88 |
abc1234 | Link a commit by short SHA | a3f2b9c |
user@abc1234 | Commit in user’s fork | alice@a3f2b9c |
org/repo@abc1234 | Commit in another repo | acme-co/widget@a3f2b9c |
Mentioning users
In any comment, issue, PR, or commit message
Thanks for the report, @alice. @bob can you review when you get a chance? cc @charlie — relevant to your work on the cache.
@usernamenotifies the user (if they’re a collaborator or have access).Users can disable notifications globally; mentions still create a link.
"cc" is convention for "for awareness, no action needed".
Mentioning teams
In an org repo
Heads up @acme-co/backend — schema migration in this PR.
Notifies every member of the team (unless they’ve opted out). Prefer team mentions over @-ing five people individually.
Issue and PR references
Same-repo references
Related to #88 See discussion in #142 Duplicate of #51
Cross-repo references
Blocked on acme-co/design-system#22 Depends on backendapi changes in acme-co/api#400
Auto-closing issues
Closing keywords in a PR description (or commit message merged to the default branch) auto-close linked issues when the PR merges.
Closing keywords
close closes closed fix fixes fixed resolve resolves resolved Examples in a PR description: Fixes #142 Closes #150, fixes #151 Resolves acme-co/api#400
Must be in the PR description (not a comment) to show as “linked” in the UI.
Works in commit messages too, but only when merged into the default branch.
Cross-repo closing requires the user to have write access in the target repo.
Commit references
Linking commits
The regression started at a3f2b9c. Reverted in acme-co/widget@b71ef02.
A 7-character (or longer) SHA is auto-linked. Use the full SHA for unambiguous references when the short hash is ambiguous in large repos.
Permalinks to specific lines
y to swap the URL for a permalink (pinned to the current SHA). Paste it into an issue or comment and GitHub renders the actual code snippet inline.The permalink format
https://github.com/acme-co/widget/blob/a3f2b9c/src/utils/parse.ts#L42-L58
^^^^^^^ ^^^^^^^^^
commit SHA, not a branch line rangeSuggested changes in reviews
In a PR review comment, the ± button (or fenced block with suggestion) lets you propose an exact edit the author can apply with one click.
A suggestion block
Looks good, small rename: ```suggestion const totalIncludingTax = subtotal + tax ```
When mentions notify
Not every reference creates a notification. The rules:
@usernamealways notifies, unless the user has globally muted notifications from this repo.@teamnotifies every team member (unless individually opted out).#123does not notify; it just creates a link.Editing a comment to add a mention notifies the newly-mentioned user.
Repo watchers get all notifications for their watched events; mentions are louder.
Etiquette
Don’t @-bomb. Mentioning a person is asking for their attention. Use it sparingly.
Prefer team mentions when you really need a group; people on the team can self-route.
Don’t @-everyone. Use a label, a milestone, or a project — not a notification storm.
Use “cc” liberally for FYI; “please” when asking for action.
Avoid @-mentions in commit messages unless absolutely necessary — every reword sends fresh notifications.
Off-hours — consider whether a mention can wait until business hours. Most can.
Quoting comments
Reply with context
> I think we should rate-limit at the API gateway. Agreed @alice — proposing it in PR #214.
GitHub also has a built-in Quote reply option in the ⋯ menu on any comment.
Common pitfalls
@-mention of a non-member silently fails — they can’t be notified if they don’t have access.
Closing keyword in a comment, not the description — issue won’t auto-close. Edit the description.
Branch-relative URLs for code references — break when the branch moves. Use permalinks.
Cross-repo closing without permissions — won’t close. Coordinate with the other repo’s maintainer.