Table of contents
Linking Git Commits to Jira Issues
To create a link between your Git commit and a Jira issue, developers must include the issue key into the commit comment.
For example, the “PRJ-50 fixed issue” comment – this assumes that you have configured a Jira project with the key ‘PRJ’ and someone has created the issue #50 within this project.
Commits are selected by issue key. Developers should add them to comments every time the commits are made.
Example Git commit message: “GIT-913 - Plugin version…”. In this case, “GIT-913” is the issue key linking the commit message to the Jira issue.
As a best practice to work with subtask — put the parent and subtask Jira issue keys in the commit message so that the commit shows in both places. This way, the commit for the subtask does not get lost in the many commits of the parent issue.
The Git Integration for Jira app supports commits that used the old Jira key in the commit message after a project rename to a new key name (Example: TEST-16 to PROJ-16).
There are two scenarios related to the rename/move:
- The Jira project key was renamed and the commit message contains the old key prior to the installation of the Git Integration for Jira app.
- The Jira issue was moved from one project to another project and the message contains the old key prior to the installation of the Git Integration for Jira app.
Only the commits that are linked to Jira issues will show on the Jira Activity Stream (not all commits in repositories).
Manually Link Git Commits to Jira Issues
To manually associate a git commit to a Jira issue, access the Change commit issues feature from the following locations:
- Project page > Git Commits > click View Full Commit.
- Issue page > Git Commits tab > click View Full Commit.
- Git menu > View all repositories > select a repository with git commits.
Click the Change commit issues label. The following dialog is displayed:
Add, edit or delete linked Jira issue keys in the Associated issues to commit field.
- JIRA administrators can add/remove any association.
- Project administrators can add/remove any association in that project.
- The authors of the commit can add/remove the association, if they have the View Development Tools access.
If the commit is associated with multiple Jira issues, you will see the following:
In the above example, the selected commit is associated with Jira issues TEST-1, TEST-2 and PROJ-4 separated by commas.
Using the above example:
- To associate the commit to an issue, insert a new issue key separated by a comma.
- To remove commit association to an issue, delete the issue key.
Click Save to save the changes.
Starting v2.6.21, the Git Integration for Jira app displays git notes in the Git Commits tab:
For a git repository with several existing commits in it, commit authors can associate issue keys via git notes to these commits without having to edit the commit messages. The Git Integration for Jira app will index issue keys in git notes.
Smart commit actions are also supported in git notes.
Each commit can only have one git note per namespace. There can be multiple note namespaces per commit. These note namespaces are automatically indexed.
Guidelines for adding new git notes:
- add git notes to new commits which has not been indexed yet;
- git notes can be added to old commits which is already indexed - but does not have an issue key.
Adding a git note to an already reindexed commit:
git notes add -m 'TST-3 is also fixed' 107af254 git show -s 107af254 git push origin refs/notes/*