GitClear can interpret multiple ways of referencing an issue from one’s issue tracker.
There are a few places that GitClear will search when we’re looking to understand which issue a particular commit addresses.
Commit message. The most unambiguous signal that a commit addresses an issue is that the commit references that issue in its commit message. Example: This work resolves ABC-123
will be interpreted to resolve issue “ABC-123” if a Jira connection has been made where there exists a project that uses he key “ABC”
Branch name. If the name of the branch mentions an issue identifier but the commit message does not, then we will interpret an issue reference through the branch name. Example: abc-123-implement-cool-feature
would serve to assign any commits made to the branch to the “ABC-123” issue.
PR title and description. If neither the branch name nor the commit message offers clues as to which issue is being addressed by a commit, we will search the PR title and description for references to a particular issue. Example: This PR implements a bunch of great features that are mentioned in ABC-123
would link all currently unassigned commits in that PR to the “ABC-123” issue.
Since many GitClear customers will work across tens of Jira projects and/or tens of repos, we do our best to automatically detect how you refer to issues. The first step toward automatic detection happens when you initially connect to Jira, at which point we will index all of the projects associated with your account, and we will begin to search out references to those projects in the locations mentioned in the "Where we look for references" section.
But sometimes teams will use more generic or esoteric ways to refer to an issue. The canonical “generic issue reference” is for a commit message to refer only to the issue number, e.g., This work resolves #123
. In which project should GitClear look for Issue #123? This is where Issue Mapping settings come into play. Using the Issue Mapping settings, you can specify on a per-repo basis which project key should be implicitly assumed when a developer generically refers to a ticket number.