Git Version Control Viewer
Installation Guide
The Git Version Control Viewer plugin is intended for displaying list of commits linked with
particular a JIRA issue. It is often useful to figure out real issue progress as well as contributors
involved in the real work of an issue.
Plugin requirements
The Git Version Control Viewer plugin requires Atlassian JIRA 5.0 or greater. If you need
to run the plugin with JIRA 4.x please contact the BigBrassBrand support team directly
([email protected]).
How To Link Git Commits to JIRA Issues
To create a link between your Git commit and a JIRA issue developers must include the issue
key into commit comment. Example of such comment is “GIT-50 fixed issue”. This comment
assumes you have configured JIRA project with key ‘GIT’ and someone has created issue #50
within this project.
Terms
Remote repository
Remote repository is the central hosting used by your team for pushing commits and
pulling updates.
Local repository clone
Clone of remote repository located on same server as your JIRA service. It is cached
locally for performance reasons and queried every time list of git commits is displayed.
Lucene indexes
Lucene is an index service within your JIRA instance. It ships with JIRA and Git Version
Control Viewer also makes use of it. The plugin keeps a separate index stored in ‘home/
caches/indexes/plugins/jira-git-revisions’.
This database stores information about all commits (comment, author, etc) as well as the
branch name which the commit belongs to.
GitRevisionIndexerJob
Revision indexer is the background job that is running within your JIRA instance. This
background job is executed every several minutes (delay is configurable on JIRA
services configuration screen). For every configured repo this process do following:
● Updates local clone of repository
● Updates lucene index with commits added recently
Note that due async structure of plugin commits becomes visible after revision indexer
job has ran and commits have been registered with index. To show commits immediately
you have to trigger reindex manually
Installation
Installation through Atlassian Marketplace
1. Go to the Git Version Control Viewer Atlassian Marketplace page.
2. Buy or evaluate the plugin with a free 30 day trial.
Installation through JIRA plugin manager
3. In JIRA - go to Administration/Plugins/Find New Plugins page.
4. Search Marketplace with ‘git’ search phrase
5. Buy plugin or start free trial for 1 month
Manual installation
Use manual install if you a specific version of Git Version Control Viewer
1. Go to Administration/Plugins/Manage Plugins
2. Click Upload Plugin and point to the jar file you have
Entering license details
Most recent versions of JIRA require entering the license on the Administration/Plugins/Manage
Plugins screen. Old versions may require you to enter the license in the plugin configuration
(Administration/Git Version Control Viewer/License)
Configuring plugin
Configure git repository
Your JIRA server must have its own clone of the git repository. SSH keys need to be configured
correctly as well. The following conditions must be met:
● ssh keys should be in /home/jira/.ssh (assuming that JIRA application uses ‘jira’ user to
run by default)
● ‘git pull origin master’ must be executed without any user intervention. This means keys
must have no password and remote repo host must be accepted as valid and included
in ‘known_hosts’ file
Example of git output for git host that has never been accepted before
List of configured repositories on the plugin administration pages
Adding repository
Repositories are added on repositories list screen. Press ‘Add’ link to add repository. Several
repository settings must be specified:
Repository Root - this is path to the repository on server where your JIRA service is
running
Repository Origin - url to hosted git service used on project. For example, you might host
your repository on GitHub, Beanstalk, or on own server. Note: the repository origin may
not be hosted on the same server as JIRA.
Status - Repository status. Active if Repository Root is configured correctly and JIRA
instance can access it.
Last indexed : Date and time when synchronization was last executed.
Modifying git repositories
There are four actions available for repository:
● Edit - edit link to Git repository
● Delete - delete link to Git repository
● Reset - clear last indexed revision and rebuild Lucene index on next synchronization
● Re-index - start synchronization with remote repository immediately
Add/Edit repository screen
●
Repository Root - see ‘Adding repository’
●
●
●
Repository Origin - see ‘Adding repository’
Revision Indexing - this option turns on memory cache which is used when list of
commits displayed.
Revision cache size - size of memory cache above. If some particular commit is not in
cache it is fetched from Lucene index (this may involve some disk activity).
Web linking
Web linking feature adds links to your git hosting provider directly into Git Commits tab panel.
Following providers are supported:
● cgit
● Fisheye
● GitHub
● Gitorius
● gitweb
Custom configuration can be created to support other git hosting providers. 4 urls should be
configured for setup that:
ChangeSet Format - url used to display revision. Variables available:
● {rev} - git revision
File Added Format, File Modified Format, File Deleted Format - url to show content of added/
modified/deleted files. Following variables are available:
● {num} - number of change (0, 1, ….)
● {rev} - git revision
● {path} - path of file changed
● {parent} - parent git revision
● {blob} - id of blob object
● {parent_blob} - id of parent blob object
View Format - this url is not used at the moment.
Issue TabPanel
If the plugin is configured and licensed successfully then a new tab is added to each JIRA issue.
Commits are selected by issue key, so developers should add issue key to comment every
time they are making commits. Commits included in non-master branches being included only if
master branch doesn’t have them.
Example Git commit message: “TST-1 testing http access to repo”. In this case, “TST-1” is the issue key and
is what links the commit message to the JIRA issue.
●
●
●
●
●
●
Repository/Indexed - Repository name (as in plugin config) and date of last
synchronization with remote repo
Branch - Git branch name
Date/Revision - date of commit and revision id
Author/Committer - author of commit
Message - commit comments
Files Changes - list of files affected by commit
Reindexing
Synchronization between the repository and plugin will start automatically, but sometimes
reindexing is required to manually start the synchronization process. There are 2 options to do
this:
1. To start update of all repositories go to the Git Version Control Viewer plugin re-indexing
tab and press Re-index button. Once synchronization is started, progress will be shown
on this tab.
2. If a specific repository needs to be synchronized go to ‘Git Repositories’ tab, find the
repository and click on ‘Re-index’ link.
Upgrading old versions of plugins
1.
2.
3.
4.
5.
6.
7.
8.
Remove any repositories from plugin config
Remove old JIRA git plugin on JIRA Administration/Manage plugins page
Remove Git plugin indexing service
Remove old lucene indexes (home/caches/indexes/plugins/jira-git-revisions)
Install plugin, verify that plugin is enabled
Add repositories to plugin config
Verify that each JIRA ticket has ‘Git Commits’ tab
Verify that initial synchronization has completed