Automatically Linked References in Pull Requests and Commit Messages
When pull request or comment is posted, the text description is parsed in search for references. These references will be shown as links.
Likewise, commit messages are parsed when they are listed.
To prevent the creation of unintended references, there are certain rules for them to be recognized. For example, they should not be included inside code text. They should also be reasonably cleared from their surrounding text (for example, using spaces).
User, Team and Organization Mentions
When a text in the form @username is found and username matches the name
of an existing user, a mention reference is created. This will be shown
by changing the text into a link to said user's profile, and possibly create
a notification for the mentioned user depending on whether they have
the necessary permission to access the contents.
Example:
@John, can you give this a look?
This is also valid for teams and organizations:
@Documenters, we need to plan for this. @CoolCompanyInc, this pull request concerns us all!
Teams will receive mail notifications when appropriate, but whole organizations won't.
Commit messages do not produce user notifications.
Commits
Commits can be referenced using their SHA1 hash, or a portion of it of at least seven characters. They will be shown as a link to the corresponding commit.
Example:
This bug was introduced in e59ff077
Pull Requests
A reference to pull request can be created using the simple
notation #1234, where 1234 is the number of pull request
in the same repository. These references will be shown as links to the
referenced content.
The effect of creating this type of reference is that a notice will be created in the referenced document, provided the creator of the reference has reading permissions on it.
Example:
This seems related to #1234
Pull requests in other repositories can be referred to as well
using the form owner/repository#1234:
This seems related to mike/compiler#1234
Alternatively, the !1234 notation can be used as well.
Pull Requests References Summary
This table illustrates the different kinds of cross-reference for pull requests.
In the examples, User1/Repo1 refers to the repository where the reference is used, while
UserZ/RepoZ indicates a different repository.
| Reference in User1/Repo1 | Repo1 Pull Req are external | RepoZ Pull Req external | Should render |
|---|---|---|---|
#1234 | no | - | A link to pull 1234 in User1/Repo1 |
!1234 | no | - | A link to pull 1234 in User1/Repo1 |
#1234 | yes | - | A link to external PR 1234 for User1/Repo1 |
!1234 | yes | - | A link to PR 1234 for User1/Repo1 |
User1/Repo1#1234 | no | - | A link to pull 1234 in User1/Repo1 |
User1/Repo1!1234 | no | - | A link to pull 1234 in User1/Repo1 |
User1/Repo1#1234 | yes | - | A link to external PR 1234 for User1/Repo1 |
User1/Repo1!1234 | yes | - | A link to PR 1234 for User1/Repo1 |
UserZ/RepoZ#1234 | - | no | A link to pull 1234 in UserZ/RepoZ |
UserZ/RepoZ!1234 | - | no | A link to pull 1234 in UserZ/RepoZ |
UserZ/RepoZ#1234 | - | yes | A link to external PR 1234 for UserZ/RepoZ |
UserZ/RepoZ!1234 | - | yes | A link to PR 1234 for UserZ/RepoZ |
| Alphanumeric PR IDs: | - | - | - |
AAA-1234 | yes | - | A link to external PR AAA-1234 for User1/Repo1 |
!1234 | yes | - | A link to PR 1234 for User1/Repo1 |
User1/Repo1!1234 | yes | - | A link to PR 1234 for User1/Repo1 |
| Not supported | - | yes | A link to external PR AAA-1234 for UserZ/RepoZ |
UserZ/RepoZ!1234 | - | yes | A link to PR 1234 in UserZ/RepoZ |
The last section is for repositories with external pull requests trackers that use alphanumeric format.
-: not applicable.
Note: Automatic references between repositories with different types of pull reuests (external vs. internal) are not fully supported and might render invalid links.