Git Integration for JIRA
SERVER CLOUD v2.10.4

Introduction

The Git Integration for JIRA open in new tab add-on is intended for displaying list of commits linked with a particular JIRA issue. It is often useful to figure out real issue progress as well as contributors involved in the real work of an issue.

The Git Integration add-on pulls data from a Git source code control repository. Your JIRA users will be able to see code in Git in context with JIRA projects and issues. Even non-technical users without Git access will be able to work with Git in the familiar JIRA interface.

New tabs are added to the Issue view called Git Roll Up and Git Commits. The Git Commits tab is also added to the Project view. Users who access these tabs will see the Git activities.

fyi
Ask your Git administrator if you need access to the Git repository just like a regular developer would have. Click here open in new tab to send an e-mail using the default email program to the Git administrator.
If you are the Git administrator, define a new Git user for this JIRA server.
Get new product notifications and feature updates from BigBrassBand LLC.

Add-on Requirements

warning
Starting v2.9.0 of the Git add-on, Atlassian JIRA 6.3 or later is required.
Universal Plugin Manager 2.2 or later is required to properly install this add-on.

Permissions Requirement to Display Commit Information

warning
Users must have ‘View Development Tools’ permission in order to view commit information on the issue page.

The user needs to be in the developers group to view code diffs when default permission scheme is used.

View Development Tools Project Permissions

Consider the following criteria when setting permissions:

  • Permission name may be different depending on your version of JIRA.
  • Project permissions are configured on the project administration page. Different projects may have different permissions.
  • Default permission scheme grants access to add-on to all members of administrators and developers groups. No additional configuration is required in this case.

Getting Started for Git Administrators

For detailed information on this topic, see Git Integration for JIRA for Git Administrators open in new tab.

For information on troubleshooting known errors and issues, see Git Integration for JIRA - Knowledge Base open in new tab.

Installation

If the Git server and JIRA server are installed on the same server, only the path to the Git repository is needed.  The URL and the access credentials to the Git server will only be needed if it is located on another server.

warning
You must have the JIRA System Administrators global permission to install add-ons.
FYI
If you have the previous version of the Git add-on and will upgrade to v2.5+, all existing repositories in the add-on configuration will have the Repository Browser feature turned off by default. For more information about this feature and how to enable it, see The Repository Browser.

 

Installation via Atlassian Marketplace

  1. Go to the Git Integration for JIRA open in new tab Atlassian Marketplace page.
  2. Buy Git Integration for JIRA add-on
  3. Buy or evaluate the add-on with a free 30 day trial.
  4. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses. For purchased license keys, see Managing License Key.

Installation via JIRA Plugin Manager

  1. In JIRA, go to cog Administration > Add-ons.  The Find New Add-ons page is displayed.
  2. Search and install the Git add-on
  3. Search the Marketplace with 'git' or 'bigbrassband' search phrase.
  4. Buy the add-on or start the free trial for 30 days.
  5. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses. For purchased license keys, see Managing License Key.

Manual Installation

warning
To manually update the Git add-on, the user must have the JIRA System Administrators global permission.  If the user does not have this permission, the upload add-on and other system administration functions will not be available.

Download the Git add-on installer package from Atlassian Marketplace:

Git for JIRA add-on version history at the Atlassian Marketplace

Use manual install if you have a specific version of Git Integration for JIRA downloaded from the marketplace or sent by some other file sharing method.

  1. In JIRA, go to cog Administration > Add-ons > Manage Add-ons.
  2. Find and select Git Integration for JIRA in the User-installed add-ons list.
  3. Click Disable.
  4. Click Uninstall to remove the Git for JIRA add-on.
  5. Scroll up and click  add-on upload Upload Add-on  and navigate to the Git add-on jar file that you have downloaded.
  6. Click Upload.
  7. Buy the add-on or start the free trial for 30 days.  Skip this step if this add-on was already purchased.
  8. Login to your JIRA account, if required, to proceed installation of the add-on.  The license key is automatically configured into the add-on configuration for free trial licenses.  For purchased license keys, see next section.

Installation and Updating

For upgrade installations it can be easily done via Universal Plugin Manager (Manage Add-ons).

There are two ways to do this:

  • Automatic upgrade installation via the Git add-on Upgrade button, or
  • Git add-on update installation via UPM
  • Manual upgrade installation via the UPM > add-on upload Upload Add-on.
  • Git add-on manual installation/update via UPM To manually update the Git add-on, the user must have the JIRA System Administrators global permission.

Watch the video below on how to update your version of Git Integration for JIRA add-on via UPM (Universal Plugin Manager).

The updating process is demonstrated in two chapters:

  1. Automatic updating via UPM (0:05)
  2. Manual updating via UPM (0:48)

 

Managing License Key

Go to the Git Integration Plugin for JIRA add-on configuration (Manage Add-ons).

Git plugin manage license keys

Click the pencil icon Edit icon to enter/change the License key.

helpful tip
If the License key field is blank, you need to obtain a license for the Git Integration add-on. Click Buy now or Free trial. Login to your Atlassian account, when prompted, to acquire the license based on your selected license mode.
note
Old versions of the add-on may require you to enter the license in the add-on configuration (Administration/Git Integration for JIRA/License).

Working with SSH Keys

SSH keys are required in order to provide secure connection with the remote git host specified in the Repository Origin field.  The add-on uses one set of keys for accessing all configured repositories.

There are two options available for specifying SSH keys:

  • SSH keys stored on server filesystem are located in the home folder of the user which account is used to run JIRA.  This option provides better compatibility with installation of the previous versions of the add-on. This option does not support passphrases.
  • SSH keys are stored in the add-on configuration. Keys are added using the add-on configuration.  This option supports passphrases.

List of SSH Keys

Both types of SSH keys are displayed on the SSH Keys tab.  Legacy filesystem-based keys contain directory path in the Private key column.

note
You cannot delete filesystem-based key using add-on configuration.
FYI
The SSH keys are also automatically added to this list when adding new repositories that require SSH keys.

Public Key and Private Key with SSH

Generated ssh keys always come in pair. (Example: id_rsa.pub and id_rsa)

For establishing safety connection with SSH, upload a Public Key to the SSH server and set the Private Key to the SSH client.

Take note that the SSH server is the Git server and the SSH client is the JIRA server.

  • Git server  —  Public Key
  • JIRA server — Private Key (Git Integration Plugin for JIRA > SSH Keys)
note
The developer’s local system should not have the same private key.

Generating SSH Keys

Configure and generate SSH keys for the following git hosting systems by following the reference links on each sub-section:

Beanstalk
Github
Bitbucket
Git-scm (Windows)
GitLab
Gitolite
Gerrit

By v2.6.1 of the Git add-on, the Gerrit web linking support is added.

GitBlit
Team Foundation Server

The SSH support starts with TFS 2013 and later versions.

note
Users can use HTTPS or SSH to securely connect to git repositories.  HTTPS connections will require the user's login credentials, while SSH connections will require SSH keys.

Adding an SSH Key

 

Go to cog Administration  > Add-ons. Click Manage Add-ons on the sidebar. Under Git Integration Plugin for JIRA, select SSH Keys.

helpful tip
If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select SSH Keys.
Add SSH key and associate to repository(ies)
Column Description
Name Name of the added SSH key
Private key This is the SSH key in hex mode.
Passphrase Defines true if the SSH key has a passphrase.
Associations Lists the associated repositories with this SSH key.
Last Used By Defines the repository that is using this SSH key.
Operations Click the icon to perform Delete and Associations functions.

Click Add SSH Key to configure the SSH key. The following screen is displayed:

Add SSH key input screen
helpful tip
You can upload the private key file via Browse... or paste the key into the Private key field.

Utilize the following options for the new SSH key:

Option Description
Name Enter a meaningful name for this private SSH key.
Private key This is the actual private SSH key.
Paste private key from clipboard or load from a private key file.
Passphrase Optional.  Enter the passphrase that you have assigned to this private key.

Associating an SSH Key to a Repository

Limit the usage of the SSH key only to the selected repositories.  As of v2.6.9 of the Git add-on, the option to strictly map keys to repositories is available.

On the SSH Keys page, click cog Actions > Associations for the selected SSH key.

The following screen is displayed:

Associate SSH key config screen

Mark the required repository or repositories to associate the SSH key.

Clicking the  Select All  text label marks all repositories that will be associated to this SSH key.

Clicking the  Select None  text label deselects all repositores.

Click Save to save the settings.

FYI
If an SSH key is strictly associated with some repository, that SSH key is an associated key.

If you have multiple repositories that uses the same SSH key that you want to connect with the Git add-on, you need to:

  1. Configure a repository that requires an SSH key via Add Repository Wizard.
  2. Associate that SSH key with currently configured repository via SSH Keys.
  3. Add another repository that requires the same SSH key.  You will be presented with the following screen:
  4. Associate existing ssh key to added repository
  5. Select the SSH key that you have associated to the previously added repository from the Existing key list.
  6. Click Next to continue.  Complete the wizard and add another repository as desired.

Removing SSH Keys

SSH keys cannot be modified or updated.  To change the keys, remove and add them again.

note
If the key is deleted, all repository references will also be removed.  Repositories that don't have the key associated to them will use the common keys by default.

Reconfigure Git Repository and SSH Key

Perform the following steps to reconfigure repositories and SSH key:

  1. Remove any old SSH keys configured with the Git add-on via <JIRAHOSTNAME> /secure/ViewSshKeys.jspa
  2. Restart JIRA.
  3. Get the following file from your JIRA server to your Windows workstation: /home/jira/.ssh/id_rsa
  4. Set up the git repository in JIRA using the repository location and upload the private key that was downloaded above.

For multiple repository configuration, see Bulk Change.

Git URL Ports

If your JIRA and Git servers are running through a firewall, configure the firewall to allow access using the URL schemes for git repositories. For authentication issues, make sure to check first the correct port for its connection.

Below are the default ports for common git URL protocols:

Protocol Default Port
ssh:// port 22
git:// port 9418
http:// port 80
https:// port 443

Test git connection and repository URL by doing the following:

  1. Install git client (or run sudo apt-get install git)
  2. Place your ssh key into ~/.ssh
  3. Clone the repository (or run git clone <your_repository_url>)
note
The Git Integration for JIRA will run successfully if the above connection test ran without errors.

Setting Up Repositories

Setup repositories and manage them in the Git add-on configuration in JIRA.

 

In this page, a git host/server can be connected to JIRA via the Connect to Git Repository button.  Administrators can perform the Bulk Change action to import/export git repositories into JIRA via a TSV file.

The Reindex All action will reindex all repositories/servers in the Git configuration list.

The Git configuration list displays the connected repositories/servers, location, enabled/disabled state, display name, last index and status.

To the right of the Status column are actions that can be performed for the selected connected repository/server.

warning
When setting up repositories with the Git add-on, you need to have the necessary access permissions on the private key on the Git server to proceed.
note
For cases when git repositories are hosted at Windows servers (Windows Server network drive) — while it is using the Windows server networking, the network credentials accessing the git repository must be the same as the user running JIRA.
warning
When using Windows network shares for the repository origin, it is recommended to allocate repositories’ paths shorter than 256 characters.
For example: \\WS129\custom-repo\project-z\
Otherwise, the provided URL will not be recognized as valid.
FYI
For JIRA hosted on Windows:
When using Active Directory accounts for repository access, changing the password of the AD account running JIRA can cause repository authentication issues.
The solution for this is to restart JIRA to regain access to repositories.
FYI
As of v2.8.3 of the Git add-on, the REST API for add, update, and delete repository is implemented.  The documentation for this feature is available at Git add-on: Hook and API Reference - Repository REST API open in new tab.

Using the Add Repository Wizard

Go to cog Administration  > Add-ons  >  Git Integration Plugin for JIRA  > Git Repositories.

helpful tip
If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.

Click Connect to Git Repository.  The Add Git Repository wizard is displayed.

Connect to Git Repository wizard start screen

Enter required repository location.

Click Next. The wizard will automatically detect the entered repository location type.

FYI
Detection of Remote Origin Setting
The detection works for most repositories. If a repository root points to a valid git repository, the repository origin is detected automatically.  When a repository has no origin, the user has to specify it manually.
note
Do note that the repository wizard clones the remote repository by default.  It does not clone local repositories. For local repositories, it sets root to local path and disables fetches.

Starting v2.6.7 of the Git add-on, the default identities are not used and the repository is created without the additional key upload.
helpful tip
If the Git repository file system is somehow available to the JIRA server, you can save the clone step and save the disk space on a JIRA server by pointing the JIRA server straight at it.

Settings

In the Settings screen, enable or disable the Git Viewer feature for this repository as required.

[Connect to Git Wizard Settings screen

Enable or disable the Smart Commits setting for this repository as required.

Enter available projects as required in the Associate Project Permissions field or check the Associate to All projects checkbox to associate all projects.

note
The View Development Tools project permission must be granted to Users > Group > Project Roles.

Click Next.

HTTPS Authentication

If the entered git host requires http credentials, the following screen appears:

Connect to Git Wizard http authentication screen

Provide Username and Password in the respective fields then click Next to continue.

Connect to Git Wizard ssh authentication screen

Configure the required SSH private key by navigating to the private key file or pasting the private key text into the pastebox.

note
For establishing safety connection with SSH, upload a Public Key to the SSH server and set the Private Key to the SSH client. Take note that the SSH server is the Git server and the SSH client is the JIRA server.
helpful tip
When adding a new repo that requires an SSH key, you can now pick an existing associated key in the Existing key list.

Click Next to proceed.

Passphrase Input

Connect to Git wizard authentication screen passphrase

Enter the Passphrase, if required. Click Next to continue.

note
The passphrase screen only appears if the user has added an SSH key that requires a passphrase.
FYI
The Git add-on will try first to use the keys provided by the user before using the keys from the home directory.

After the above requirements are fulfilled, the wizard will:

  • create a local copy of the git repository; and
  • index the git repository to build change history.

Click Finish to close the wizard.  The newly added repository appears on the git repositories list of the add-on.

Adding a Repository via Advanced Setup

warning
As of v2.6.12, the Git add-on supports repositories that do not have a branch named "master".

Use the Advanced setup if you have set up the Git repository ahead of time outside of the JIRA Git add-on.  Configure repositories via Advanced setup in order to manage advanced options.

Open the Connect to Git Repository wizard then click the Advanced Setup label.

The following advanced setup screen is displayed:

Connect to Git - Advanced Repository settings

Enter the required information.

Utilize the following options for adding new git repositories:

Repository Settings
Display Name  –  This is the name that will appear in the Git add-on repositories list. (Required)
Repository Root  –  This is the local path to the repository on the server where your JIRA service is running.  This will point the Git add-on to a clone of the repository hosted locally with JIRA. (Required)
Enable Fetches
Git repository hosted on remote server
In this mode, fetches are enabled using any external source. The reindex background service will initiate the fetch then add the new commits to the plugin index.
Git repository hosted on same server as JIRA
Fetches are enabled when the repository is hosted locally. In this mode, no fetches are made. The reindex service runs in the background and process every new commit found.
Repository Origin
This is the URL to the hosted git service used on the project.
For example, you might host your repository on GitHub, Beanstalk or your own server.
FYI
The repository origin may not be hosted on the same server as JIRA.

The detection works for most repositories. If a repository root points to a valid git repository, the repository origin is detected automatically. When a repository has no origin, the user has to specify it manually.
Revision Indexing
This option turns on the memory cache which is used when list of commits are displayed.  Select if revision indexing will index and link to any mentioned issue keys in the revision history or not.
Revision Cache Size
This is the size of the memory cache.  If some particular commit is not cached, it is fetched from the Lucene index which involves some disk activity.
Enter the number of revisions to keep the cache in memory.  The default value is 10000.  Higher values can affect the performance of the retrieved revisions from Git.
Tags
Show all tags  –  This will display all the tags for the specific issue.
Show tags matching the pattern  –  This will display tags on issue pages that match the specified regular expression pattern.
release2[.](7|8)[.][0-9]+
This example is a filtering regexp for a range of releases from 2.7.x to 2.8.x.  The sidebar will display git tags for release versions 2.7.0 to 2.8.x in decending order.
Main Branch
Specified branch will intend to organize the git commit tab.  A commit will not be shown in other branches if it is a part of the main branch.  By default, "master" will be used if a main branch is not specified.
Use basic http authentication
Most git hosts provide http access to git repositories.  Enter required credentials to configure basic http authentication to remote git repositories.
Repository Browser
Advanced setup - Git Viewer and Project Permissions
Enables or disables the Git Viewer feature for this repository. The default setting for this option is Enabled.  Users must have the View Development Tools project permission in order to use this feature.  Consult your JIRA System Administrator on permissions.  For more information, see section, The Repository Browser.
Project Permissions
Associate Project Permissions  –  One or more projects must be mapped to this repository to make Git Commits tabs available in the Issue screens of the associated projects.
FYI
This field requires at least one existing project if the Repository Browser for this repository is enabled.
Associate with all projects  –  Enable this option to associate this repository to all projects.  Disable this option if you want to use existing mapped projects from the Associate Project Permissions field.  The default setting is enabled (checked).
Smart Commits
Advanced setup - Smart Commits and Email Notifications
See section, Smart Commits.
This setting is enabled by default (as of v2.6.3 of the Git add-on).
Commit Notification Emails
Send notifications  –  Enables or disables commit notification emails for this repository.
Max. commit age in minutes  –  Set the desired value in minutes, as to when commit notifications will be sent.  Commit notifications will be e-mailed if the age of the commit is less than or equal to this value.
Weblinking
The Weblinking configuration is optional.  For more information about this option, see section, Weblinking.

Click Add to save the settings.  The newly added repository appears on the git repositories list of the add-on.

Repositories created via the Advanced setup will perform an initial reindex.

Adding a Repository Hosted on Windows Servers or Windows Network Share

Add a new network share or Windows server hosted repository via the Connect to Git Repository wizard.

The wizard will continue without errors if the following conditions are met:

  • The network credentials accessing the git repository must be the same as the user running JIRA.
  • The network path is not longer than 255 characters.
  • The user under which JIRA is running should at least have read access to network path.

In the Git configuration page, edit the repository via Actions > Edit repository.

Under Repository Settings, set Enable Fetches option to Git repository hosted on the same server as JIRA.

Windows network share git repository on same server

Verify network folder share name by opening the shared folder properties:

For example:

Windows network shared folder properties

Make sure that the user has read access permissions to the network path.

For example:

Windows network shared access permissions properties

Setup Repository Root Not Located in JIRA Home Directory

There are three possible ways to setup a repository root that is not located in the JIRA home directory:

  • Clone the repository outside of JIRA then connect to it via Connect to Git Repository  >  Advanced Setup.
  • Clone the repository with the standard Connect to Git Repository Wizard into the JIRA home directory.  Soon afterwards, move the cloned repository and update the settings on the repository.
  • You could symlink the {$JIRA_HOME}/data/git-plugin directory to a different volume.  The standard Connect to Git Repository Wizard will still write there, but the data will reside on the different volume.  But be aware, that Git add-on treats anything in the Git-Plugin folder as a clone that it owns.

Adding Tracked Folders

Introduced in v2.9.0 of the Git add-on, this feature scans a locally accessible path for cloned Git repositories and automatically imports those Git repository references into JIRA.  A repository group called TRACKED FOLDER is added into the Git add-on repository settings.

warning
The Add tracked folder feature requires that JIRA and the git servers be on the same filesystem.  Make sure that the user that JIRA is running with has access permissions to the path with the git repositories.

 

To add repositories via Tracked Folders:

  1. Go to  cog Administration  > Add-ons  >  Git Integration Plugin for JIRA  > Git Repositories.
  2. helpful tip
    If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.
  3. Click the dropdown arrow on Connect to Git Repository then Add tracked folder.
  4. Add track folder dropdown The following dialog is displayed: Add Tracked Folder wizard
  5. Enter the Tracked folder location in the required field then click Scan folder.
  6. For example: /home/ec2-user/repositories/*

    In the following dialog, the wizard will find git repositories stored in the provided path and displays the list of repositories found. Found tracked folder dialog

    In the above example repository root, /home/ec2-user/repositories/*, all repositories under this mask (/home/ec2-user/repositores/<repo1>, /home/ec2-user/repositores/<repo2>) will be handled as one entry in the Git Repositories configuration page.  For other features, these are treated as seperate repositories.

    information
    The Add tracked folder wizard scans the local path one folder level deep.
  7. Click Import repositories.
  8. The wizard automatically adds the detected repositories to JIRA.  If a repository is added to the path, JIRA will add it to the index. If a repository is removed from the path, JIRA will drop the index for that repository.
  9. On the Permissions dialog, set Repository Browser and Project Association permissions, if required.  Click Next.
  10. Click Finish to complete adding the tracked folder.

The tracked folder is added to the repository configuration list.

helpful tip
You can add multiple tracked folders in case your repositories are spread among multiple locations.

Editing a Tracked Folder

On the Git Repositories settings page, click  cog Actions  > Edit tracked folder to modify tracked folder git repository settings.

Found tracked folder dialog

Removing a Tracked Folder

On the Git Repositories settings page, click  cog Actions  > Delete tracked folder to remove the tracked folder configuration from JIRA.

A confirmation dialog will be displayed:

  1. Leave the checkbox unchecked to just remove the tracked folder setting from the repository configuration list. (The local path for this tracked folder will still remain in the local system for later use); or
  2. Tick the checkbox to permanently delete the tracked folder and its files from the local system.

Reset Index

On the Git Repositories settings page, click  cog Actions  > Reset index.

This action will reset the indexes of the repositories for the selected tracked folder.

Viewing Tracked Repositories

On the Git Repositories settings page, click  cog Actions  > Show tracked repositories.

This action will open the Tracked Folder dialog showing the tracked repositories.

note
The Repository Browser will not display the repository if it is disabled in the Git Repositories configuration. The commits and code diffs in the Issue > Git Commits, Git Roll Up and Project tabs will also be unavailable due to this.

Reindexing a Tracked Folder

On the Git Repositories settings page, click  cog Actions  > Reindex tracked folder.

This action will perform a reindex of the selected tracked folder.

FYI
If a new repository is manually added into the local path, the Git add-on will detect the new repository folder on the next reindex and add it into the existing tracked folder in JIRA.
note
If a repository folder is manually deleted from the local path, the Git add-on will remove the repository setting from the tracked folder in JIRA on the next reindex.

Connecting to a GitLab Server

Introduced in v2.9.4 of the Git add-on, this feature scans a remote GitLab server and automatically imports those Git repository references into JIRA.  A repository group called GITLAB SERVER is added into the Git add-on repository settings.  This feature can import more than a hundred repositories from a GitLab server and can track added or deleted repositories upon reindex.

helpful tip
BigBrassBand recommends a dedicated user for this integration which has access permissions to the GitLab git repositories.

 

To add repositories from a GitLab server:

  1. Go to  cog Administration  > Add-ons  >  Git Integration Plugin for JIRA  > Git Repositories.
  2. helpful tip
    If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.
  3. Under Git Integration for JIRA on the sidebar, select Git Repositories.
  4. Click the dropdown arrow on Connect to Git Repository then Connect to GitLab.
  5. Connect to GitLab dropdown The Connect to GitLab wizard is displayed: Connect to GitLab Wizard - GitLab server
  6. Select the External service from the dropdown list.  For this guide, choose GitLab Server (CE/EE).
  7. Enter the Host URL of the GitLab server.  Enter the username and password credentials for server authentication.

  8. On the Repositories Found screen, the wizard will display git repositories of the git server that it finds.
  9. Found tracked Git repos dialog
  10. Click Import repositories.
  11. The wizard automatically adds the detected repositories to JIRA.
  12. On the Permissions dialog, set Repository Browser and Project Association permissions, if required.  Click Next.
  13. Click Finish.

The GitLab server is added to the repositories list as a connected server and is automatically reindexed.

Manage a Connected GitLab Server

On the Git Repositories settings page, click  cog Actions  > Edit connected server to modify tracked repositories settings.

Reset Index

On the Git Repositories settings page, click  cog Actions  > Reset index.

This action will reset the indexes of the repositories for the selected connected server.

Manage Tracked Repositories

On the Git Repositories settings page, click  cog Actions  > Show tracked repositories.

This action will open the Tracked Folder dialog showing the tracked repositories of the connected server.

Just like in the Git repositories configuration list, a tracked repository can be enabled/disabled by toggling the Enabled box of the selected repository.

note
The Repository Browser will not display the repository if it is disabled in the Git Repositories configuration. The commits and code diffs in the Issue > Git Commits, Git Roll Up and Project tabs will also be unavailable due to this.

Reindexing a Connected Server

On the Git Repositories settings page, click   Actions  > Reindex connected server.

This action will perform a reindex of the selected tracked folder.

FYI
If a new repository/project is manually added via the GitLab server, the Git add-on will automatically detect the new repository on the next reindex and add it into the existing tracked repositories of the connected GitLab server in JIRA.
note
If a repository/project is manually deleted via the GitLab server, the Git add-on will automatically remove the repository setting from the tracked repositories on the next reindex of the connected GitLab server in JIRA.

Removing a Connected GitLab Server

On the Git Repositories settings page, click  cog Actions  > Delete tracked folder to remove the tracked folder configuration from JIRA.

A confirmation dialog will be displayed:

  1. Leave the checkbox unchecked to just remove the tracked repositories setting from the repository configuration list. (The cloned repositories for this connected server will still remain in the local system for later use); or
  2. Tick the checkbox to permanently delete the tracked repositories of the connected server and its files from the local system.

Connecting to AWS CodeCommit (JIRA Cloud)

AWS CodeCommit is a git host service by Amazon Web Services to store and manage source code, related files and private Git repositories in the cloud.  This service works like a Git-based repository providing similar functions to that of a git host.

helpful tip
You can use the AWS CLI or the AWS CodeCommit console to track and manage your repositories.

For more information on AWS CodeCommit configuration and deployment, see AWS CodeCommit User Guide open in new tab.

Auto-Connect

To connect your repository to JIRA thru the Git Integration for JIRA Cloud add-on, open the Connect to Git Repository wizard:

  1. On the JIRA navbar, click Git .
  2. Select Manage Git Repositories.
  3. On the following screen, use the Auto-connect panel for automatic integration of git repositories.
  4. Git for JIRA Cloud Auto-Connect panel
    Click a git host icon on the Auto-connect panel to start connecting the git repositories for the selected git host. For this case, click on the AWS CodeCommit icon.
  5. On the following screen, select a Region then enter credentials for Access key ID and Secret access key.
  6. Click Next to continue.
  7. Click OK to complete this process.

The Git Integration for JIRA Cloud add-on supports tracked folders for AWS CodeCommit git repositories. The connected git host is scanned for existing repository folders.  The found repositories can then be added to the Git Repositories configuration.

There are two ways to configure the git repository connection using tracked folders with Git for JIRA Cloud:

  • connect via Auto-connect integration panel > AWS CodeCommit, or
  • connect via Connect to Git Repository dropdown > AWS CodeCommit.

If the connected git host has newly added repositories, the Git add-on will automatically add them to the git repositories configuration on the next reindex.  For the deleted git repositories, these will be removed from the Git add-on repositories configuration on the next reindex.

HTTP/HTTPS Connections

On the Authentication screen, enter the Access Key ID as the username.  Enter the Secret Access Key as the password.

See http://docs.aws.amazon.com/general/latest/gr/glos-chap.html#accesskeyID open in new tab for information about Access Key ID in AWS.

SSH Connections

SSH connections are handled automatically if the PUBLIC KEY was added in the AWS IAM console and the associated PRIVATE KEY was added/uploaded on the JIRA side (Git Integration for JIRA > SSH Keys > Add SSH Key).

For detailed information on managing public SSH keys in AWS IAM console, see AWS SSH Security Settings open in new tab .

If authentication issues are encountered during connecting an AWS repository to JIRA, modify the original URL by inserting the SSH Key ID as the username.  The SSH Key ID is an alphanumeric sequence provided by AWS IAM when importing a PUBLIC KEY for a particular user account in IAM.

For more information on SSH Keys with AWS, see this article open in new tab .

For example, the original URL is:

ssh://git-codecommit.us-east-1.amazonaws.com/v1/repos/test-repo

 

If the SSH Key ID 1a2b3c4d5e is applied to the original SSH URL, the resulting URL would be:

ssh://1a2b3c4d5e@git-codecommit.us-east-1.amazonaws.com/v1/repos/test-repo

 

The modified URL can now be used as a valid repository URL via Git Integration for JIRA > Connect to Git Repository.

Connecting to AWS CodeCommit (JIRA Server)

fyi
The Server version of Git Integration for JIRA add-on only accepts SSH connections.

For detailed information on managing public SSH keys in AWS IAM console, see AWS SSH Security Settings open in new tab .

SSH connections are handled automatically if the PUBLIC KEY was added in the AWS IAM console and the associated PRIVATE KEY was added/uploaded on the JIRA side (Git Integration for JIRA > SSH Keys > Add SSH Key).

For more information on SSH Keys with AWS, see this article open in new tab .

If authentication issues are encountered during connecting an AWS repository to JIRA, modify the original URL by inserting the SSH Key ID as the username.  The SSH Key ID is an alphanumeric sequence provided by AWS IAM when importing a PUBLIC KEY for a particular user account in IAM.

Like in the URL example above (Git for JIRA Cloud), insert the SSH Key ID to the original URL and use the resulting URL in the Connect to Git Repository wizard > Remote Git URL field:

  1. Go to Administration > Applications (JIRA 6.x - Go to Administration > Add-ons).
  2. On the sidebar, under Git Integration for JIRA, select Git Repositories.
  3. On the following screen, click Connect to Git Repository.
  4. Clicking the dropdown arrow will display supported git host-specific connection setup.  For this case, select AWS CodeCommit.
  5. Enter the modified URL in the Remote Git URL field.
  6. Connect to Git Repository screen - entering the modified URL in the Remote location field
  7. Click Next.
  8. Set repository options then click Next.
  9. Click OK to complete this process.

Editing a Repository

Go to  cog Administration  > Add-ons  >  Git Integration Plugin for JIRA  > Git Repositories.

helpful tip
If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.
Git Repositories - Edit repository
List of configured repositories on the add-on administration pages.

Enable/disable a repository by clicking the checkbox under the Enabled column of the selected configured repository.

Click  cog Actions > Edit repository to modify repository settings.  See Adding a Repository via Advanced Setup for detailed information on the option fields.

Click the view cog icon to see repository details:

Setting Description
Status This is the repository status. It shows updated if Repository Root is configured correctly and the JIRA instance can access it.
Last Indexed This is the date and time when synchronization was last executed.
Repository Root See Adding a Repository.
Repository Origin See Adding a Repository.
Changeset, File Added, File Modified, and File Deleted formats Displays the weblinking format strings (if set in the repository weblinking configuration).
fyi
The displayed repositories can be sorted by clicking the corresponding list header.  The add-on will remember the sorting choice per user.
note
The Repository Browser will not display the repository if it is disabled in the Git Repositories configuration. The commits and code diffs in the Issue > Git Commits, Git Roll Up and Project tabs will also be unavailable due to this.

Managing Add-on Settings with Git Repositories

The following cog Actions are available in managing add-on configuration with the git repository:

Action Description
Edit repository Edits the Git repository add-on configuration.
Delete repository Deletes the Git repository add-on configuration.
Reset index Clears the last indexed revision and rebuild Lucene index on next synchronization.
Reindex repository Immediately starts the synchronization with the selected repository.

Removing a Repository

Delete a repository if it isn't needed or is broken in the Git Plugin configuration.

  1. Go to cog Administration > Add-ons.  Under Git Integration Plugin for JIRA, select Git Repositories.
  2. helpful tip
    If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.
    Git config delete repository
  3. Click Delete repository under the Actions column for the selected repository.
  4. The confirmation screen is displayed.  Uncheck the Delete repository files... option to retain git repository files in the displayed path or leave it checked to also delete the repository files from the displayed path.
  5. Click Delete to remove the repository.  Click Cancel to abort this process.

Bulk Change

The Bulk Change feature provides an easier way to import or export repository configuration.

warning
To perform the following steps in this section, Git Add-on for JIRA v2.4 or later is required.  Please upgrade if you have a lower version of the add-on.

Exporting Repository Configuration via Bulk Change

The bulk export function allows JIRA administrators to create a backup copy of the Git ad-on repository configuration into a tab-delimited file.

  1. Go to cog Administration > Add-ons.  Under Git Integration Plugin for JIRA, select Git Repositories.
  2. helpful tip
    If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.
  3. Click  Bulk Change dropdown then select Export Configuration.
  4. Click Download to save the current configuration of your repositories to a specified location.

For detailed instructions on importing multiple repositories in the Git add-on configuration, click on the Detailed instructions label or follow the steps in the next section.

Requirement for Secured Import

Before adding repositories (new or existing) via Bulk Change, make sure that you have added SSH keys for the respective git hosts in the Git add-on SSH Keys configuration page.  For example, you have GitHub and GitLab repositories to import, add the private SSH keys to the Git add-on SSH Keys for each git host.

If you use HTTP/HTTPS URLs in the origin field, the Git add-on will not be able to import said repositories due to missing credentials.  Entering repository login credentials in the TSV file is not advisable due to a possible security risk.  Therefore, when editing the origin field of the TSV file, enter value in git@<repository-url>:[your-git-repo].git format since it will use the SSH key(s) from the Git add-on configuration instead.

Adding Existing Repositories via Bulk Change

For administrators who have several repositories, the Git add-on allows you to import multiple repository configuration using a .tsv file.  This will make managing large Git repository lists more efficient.

  1. Click Choose File... on the Import repository configuration screen.
  2. Navigate to the location of the .tsv file then click Open.
  3. Click Upload to start the import process.

The Git add-on will read the list from the file, detect the existing configured repositories, and automatically update its settings.  If an error is found, it will be displayed in the message log on the import screen and in the Status column on the repository configuration list.  Make the required changes to correct the errors on the affected rows and redo the upload.

Adding New Repositories via Bulk Change

Download the template file or follow the above section if you already have the .tsv file ready for import:

  1. Go to cog Administration > Add-ons.  Under Git Integration Plugin for JIRA, select Git Repositories.
    helpful tip
    If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.
  2. Click Bulk Change dropdown then select Import Configuration.
  3. The following screen is displayed:

    Bulk change import repository config

    Click one of the links under How to use Bulk Change? to download the template file.

helpful tip
Bigbrassband recommends that you download the example with the full configuration.

Editing Existing Repositories in the TSV File

  1. Navigate to the .tsv file and edit it with your favorite spreadsheet program.
  2. fyi
    Google Drive is also a recommended place to edit the .tsv file.

    Populate/edit the fields by utilizing the following options:

    Column/Field Description
    id Assign an ID number to a repository.  This is required if you wish to update or edit existing repositories by setting this value to their equivalent IDs.  If this field is left blank, the repository will be created as new.
    fyi
    When importing to a new server, the "id" field must be blank.
    root Optional on existing servers.  See Repository Root in section, Adding a Repository via Advanced Setup.
    fyi
    The "root" field may refer to an existing repository on a new server. If "root" doesn't exist, this field must be blank.
    origin Required.  See Repository Origin in section, Adding a Repository via Advanced Setup.

    BigBrassBand recommends to use the git@<url>:[your-git-repo].git format for the repository origin URL and adding of SSH Keys for each git host in the Git add-on configuration page.
    displayName Optional.  Define a meaningful name for this repository configuration.  If this field is left blank, the default value is obtained from the origin.
    enableFetches Optional.  See Enable Fetches in section, Adding a Repository via Advanced Setup. The default boolean value for this field is true.
    revisionIndexing Optional.  See Revision Indexing in section, Adding a Repository via Advanced Setup. The default boolean value for this field is true.
    revisionCacheSize Optional.  See Revision Cache Size in section, Adding a Repository via Advanced Setup. The default value for this field is 10000.
    mainBranch Optional.  See Main Branch in section, Adding a Repository via Advanced Setup.
    username, password Optional.  See Use basic http authentication in section, Adding a Repository via Advanced Setup.
    gitViewerEnabled Optional.  Setting this field to true will enable the Repository Browser feature for the configured repository.  The default value for this field is false.
    projectMapping These are numeric projects IDs associated with the repository.  When you create a new repository and set the field gitViewerEnabled  to true, at least one project must be associated with it.
    • This field accepts list of comma separated project IDs for project mapping. Trailing spaces are ignored (equivalent to unchecking the Associate to All Projects checkbox in the Advanced Setup dialog).
      Example: 10000,10100
    • If you change an existing repository, leaving this field blank will use the existing values of the repository configuration.
    • Setting this field to ALL will retain projectMapping settings and sets "All Projects" flag to true (equivalent to checking the Associate to All Projects checkbox in the Advanced Setup dialog).
    If projects are not associated to the repository, you must leave this field blank and set the gitViewerEnable field to false.
    smartCommitsEnabled Optional.  See the Smart Commits section. If left blank, the default value for this field is true.
    sendCommitEmails Optional.  Set commit notification emails for this repository.  If left blank, the default value for this field is true.
    maxMinsToCommitEmail Optional.  Set the desired value in minutes, as to when commit notifications will be sent.  Commit notifications will be e-mailed if the age of the commit is less than or equal to this value.  Default value is 1440 minutes.
    changesetFormat, fileAddedFormat, fileModifiedFormat, fileDeletedFormat Optional.  See the Web Linking section.
    disabled Optional.  Add this repository into the Git add-on configuration and set its status to updated (enabled) or disabled.  If left blank, the default value for this field is false.
    hosted Internal field. Read-only. This field will show whether the repository is hosted on JIRA or not.
    tagsFilter Optional.  Set tagsFilter with a valid Java regular expression or an empty string.  The filtered tags are displayed on the JIRA Developer Panel.  For more information on this topic, see Git Tags.
    integrationType Internal field. This field will show whether the repository is a tracked folder, a connected GitLab server or a simple repository.
    trackedFolderId Internal field. This field will display the ID of the "parent" repository.  It can be changed in order to convert the repository to a sub-repository.

    Use with caution. If the modified sub-repository is not located in the tracked folder, it will be removed by the sequential auto-reindex.
    delete Optional.  Set "delete" on this column/field as a confirmation to the Git add-on to automatically remove the selected repository from the plugin configuration.  If left blank, no changes will occur.
    sshKeyId This is the ID of an associated SSH key.
    note
    Take note that the .tsv file is verified by the Git add-on with the following rules:
    • The header row is required.
    • The order of fields specified in the header row – is the order of the fields in the following rows.
    • If a field is omitted from the header row, the Git add-on will use the default value for a new repository.  The Git add-on will keep the current value of a repository if it already exists in the configured repositories.
    • If a repository is not listed in the .tsv file, no changes will be made if the same repository exists in the add-on configuration.
  3. Save the file to a tab-delimited format:
    • OSX users – select all data in Numbers and then paste into a text editor and save.   Name the file with the .tsv extension (repo-example-00.tsv).
    • Excel users – save the file as Text (Tab delimited) (*.txt).  Rename file's .txt extension to .tsv.
    • Google Drive - upload the file to this service.  Right click the .tsv file then open it with Google Sheets.  Make the necessary changes then go to File > Download as > Tab separated values (.tsv) to your local machine.

Removing Existing Repositories via Bulk Change

To delete multiple repositories from the add-on configuration:

  1. Open the existing .tsv file that you want to use for this process. See the previous section for more information.
  2. Under the delete column, enter "delete" for each repository that you want to remove.
  3. Save this file and upload it via Bulk Change > Import Configuration.

Bulk Change Automation

To automate the bulk change process via script, see Bulk Change API open in new tab.

Commit Email Notifications

warning
This feature is available starting v2.6.29 of the Git Add-on.

Permissions

The user must have the following permissions to get notifications:

  • developer access to the project
  • developer access to at least one project which is mapped to the repository
  • developer access to at least one project and the repository is mapped to all projects.

Settings

Access the settings for this feature via:

  • Git add-on General Settings.
  • General commit notification setting
  • Connect to Git Repository  >  Advanced Setup and Git Repositories (sidebar) > Edit Repository screens.
  • Commit notification Advanced/edit repo screens
  • JIRA User Profile  >  Git Integration for JIRA preferences  >  Git Commit Emails.
    User profile git commit emails configuration This setting allows an individual user to receive or to stop receving any of the notification emails.

Watching

The user will get notifications when watching an issue or repository.  The user will receive repository commit notifications if that repository is being watched by the user.  If the user watches an issue, any commit related to the issue will be sent to that user as notifications.

fyi
The user will get notifications from own commits if the My Changes setting in the User Profile  >  Preferences is set to Notify me.
helpful tip
The user can watch repositories in the Repository Browser.  Select a repository under the Git menu then click the Start watching label to activate repository email commit notifications.
Watching git repository for commit notifications

User Profile Settings

By default, JIRA email notification format is text-only.

Text formatted email notification

You can change this setting to HTML by going to User Profile > Preferences. Click the Edit pencil icon.

The following dialog is displayed:

User profile update pref settings

Change the Email Type to HTML.  Click Update to save the changes. The email notifications that you receive will now be in HTML format.

HTML formatted commit email notification

View Git Clone URL and How to Cache HTTP Credentials

warning
The Clone Repo/Repository text links are only shown if at least one JIRA hosted repository exists and the project in context is associated with at least one enabled hosted repository or there's an enabled hosted repository associated with all projects.
Git configuration JIRA hosted repository example

Many git users are having trouble locating a git repository's location information for cloning as well as other common git functions.  The git repository location information can be found on the Git Repository Connection Information dialog via the Clone Repository link.

The Clone Repository link is added to the following locations in JIRA:

  • under Git Source Code in the panel on the right
  • on the Git Commits tab
  • the Git menu (Repository Browser menu) - Clone Repository menu item. This only appears when the screen has a project context - such as when viewing an issue or the project summary.

Click the Clone Repository text link to open the Git Repository Connection Information dialog. This dialog displays Git clone URL information, command line git client version requirement, instructions on cloning the repository and password caching.

General Settings

Change Git add-on settings in the Add-on Management page (Applications page in JIRA 7) to show/hide the Git Commits issue tab.

warning
Starting v2.5.9 of the Git Add-on, the option to enable/disable Git Commits issue tabs has been moved to the Add-on Management > Git Integration Plugin > General page.
JIRA 7: Administration > Applications > Git Integration Plugin for JIRA > General.

Go to cog Administration > Add-ons.  Under Git Integration Plugin for JIRA, select General.

helpful tip
If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select General.
Git Roll Up Issue Tab
General setting Git Roll Up tab group
Do not display  –  This tab is not displayed on the Issue screen for all JIRA projects.
Show for all projects  –  This tab will be displayed on the issue screen for all JIRA projects.
Show for selected projects  –  This tab will only be displayed on selected projects.  Define one or more required projects into the textbox.
Git Commits Issue and Project Tabs
General setting Git issue/proj tab group
Do not display  –  This tab is not displayed on the Issue and Project screens for all JIRA projects.
Show for all projects  –  This tab will be displayed on the issue and project screens for all JIRA projects.
Show for selected projects  –  This tab will only be displayed on the issue and project screens on selected projects.  Define one or more required projects into the textbox.
Git issue updates, tags, activity stream, email notification
JIRA Issue Updates
Enable/disable the setting to allow new commits to change the Last Updated field.  Default is enabled.  For more information about this setting, see section Reindexing – Reindex and updatedDate Filter.
Git Tags
Enable/disable the setting to have Git Integration for JIRA add-on calculate and show the Git tags in the Git Source Code panel.
For more information, see Git Tags.
Git Activity Stream
Enable/disable the setting whether to show git commits in the JIRA activity stream (Issue page or dashboard widget) or not.
For in-place upgrade of the Git add-on, this setting is turned off by default.  For new installation, the default setting is enabled.
Commit Notification Emails
Enable/disable the setting to allow sending of email notifications when a commit is made.  This setting defaults to OFF for Git add-on upgrades and ON for new installation of the Git add-on.
For more information, see Commit Email Notifications.
Repository Reindexing
Reindex interval  –  Set the automatic reindex interval frequency value in minutes as required.  Default value is 5 minutes.
Configuration of the scheduler jobs are no longer accessible in the JIRA administration page.  For this case, the Git add-on offers JIRA administrators this capability via the General screen.  Minimum value is 1.  Maximum value is 2147483647.  Only whole numbers are allowed.
Repositories Garbage Collection checker
These settings control Git repositories garbage collection.  Garbage collection process will prune all loose objects, pack loose references and repack all reachable objects into new pack files and remove the old ones.
Git repository GC checker group
GC check interval  –  Set the number of minutes that will elapse before a repository is checked to see if it should be garbage collected.  The default value is 1440 minutes.
Max loose objects count  –  Set the maximum number of loose objects that will be checked before the garbage collection is triggered. The garbage collection is activated if the number of loose objects exceeds this setting. Loose objects are single items that are not compressed into a Git pack file. The default value is 2000.
Max packed files count  –  Set the maximum number of packed files that will be checked before the garbage collection is triggered. If the number of packed files count exceeds this setting, the garbage collection is activated. The default value is 30.
Maximum Diff Line Count
General Settings Diff Limit
Max Diff Line Count  –  Set the maximum size of diffs that is allowed to be displayed in the diff dialog.  Setting this option to a higher value will affect diff display performance.

Click Save to apply the changes.

fyi
The higher the change rate of the repository, the more often it would benefit from garbage collection.
note
Every git installation has global config file and .git/config file in every git repository. All settings at the global level can be overridden at the repository level. Therefore, different email addresses can be set for every git repository.
For more details on git configuration, see Customizing Git: Git Configuration open in new tab

Web Linking

The web linking feature adds links to your git hosting provider directly into the Git Commits tab.  Configure web linking options while adding/editing repository settings so that commits can include links to the git host pages.

 

The following providers are supported:

  • Beanstalk
  • BitBucket
  • BitBucket Server
  • Bonobo
  • cgit
  • CloudForge
  • Fisheye
  • Gerrit
  • Gitblit
  • GitHub
  • GitLab
  • Gitorius
  • Gitolite
  • gitweb
  • Microsoft Team Foundation Server (starting v2013)
  • Team Services (formerly Visual Studio Online)
  • Atlassian Stash
Weblinking options example

Select a git host from the Web Link list.  The web linking input box options are automatically filled out with corresponding variables for the selected git host.  Change the variables according to the actual URL settings of the git host.  Configure server and port and ${rev} will be substituted based on the commit ID.

You can create several custom configuration to support other git hosting providers. The following five URLs should be configured for setup:

Option Description
ChangeSet Format This is the URL used to display revision.
Use the following variable: ${rev}  – git revision
File Added Format,
File Modified Format,
File Deleted Format
This is the URL to display content of added, modified or deleted files.
Use the following variables:
  • ${num} –  number of change (0, 1, …)
  • ${rev}  –  git revision
  • ${path}  –  path of the file being changed
  • ${parent}  –  parent git revision
  • ${blob}  –  ID of blob object
  • ${parent_blob}  –  ID of parent blob object
  • ${branch}  –  a branch in which the corresponding commit was made.
View Format Optional.  This URL is unused.
helpful tip
The Git Integration for JIRA add-on supports an unlimited number of repositories.
note
Some git hosts require web linking to be configured via the Git add-on add/edit repository screen (Advanced Setup).
note
The Bonobo git server requires a branch name to construct URL.

Any Git host that is accessible via SSH, HTTP, HTTPS, git protocol, local and network share is supported.

Once properly configured, the Git Commits tab on the Issues page will display as follows:

Clickable web links in Git Commits tab
fyi
The Git add-on supports custom web linking.  The commit information is displayed in the Git Commits issue tab if the git host server URL is provided on the Web Linking section in the Advanced Setup for adding/editing repositories.

Disabling Source and Commits Tabs

The Source tab is part of the FishEye Plugin and is used for integration with SVN.  The Commits tab is part of the JIRA DVCS Connector Plugin and is used for integration with gits (Git, Mercurial, BitBucket etc.).

Attlassian enables these tabs by default.

fyi
If either FishEye or JIRA DVCS Connector plugin is not installed, the Source or Commits tab will not be visible on the Issues page.

To hide the Source tab from the Issues page, disable the FishEye Plugin:

  1. Go to  cog Administration  > Add-ons  > Manage Add-ons.
  2. Find and click fisheye FishEye Plugin under the installed add-ons to expand its options.
  3. Click Disable.

To hide the Commits tab from the Issues page, disable the JIRA DVCS Connector Plugin:

  1. Go to  cog Administration  > Add-ons  > Manage Add-ons.
  2. Find and click fisheye JIRA DVCS Connector Plugin under the installed add-ons to expand its options.
  3. Click Disable.

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 “GIT-50 fixed issue” comment – this assumes that you have configured a JIRA project with the key ‘GIT’ 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.

Git Commits tab example
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.
warning
Commits that are part of non-master branches will be included only if the master branch doesn't have them.

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.

Commit association to both specific subtask and the parent issue

The Git Integration for JIRA add-on supports commits that used the old JIRA key in the commit message after a project rename to a new key name (Example: TEST1-16 to TEST-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 add-on
  • 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 add-on

Smart Commits

Smart commits allows your team to perform actions on JIRA issues from a single commit.  Users can enter the issue key and the desired action such as time tracking or closing an issue.

As of v2.6.3 of the Git add-on, the smart commit processing is active by default and can be enabled/disabled via the repository configuration:

Smart Commits setting

Smart Commits configuration checklist:

  • The JIRA DVCS Connector Plugin is not required.
  • Your JIRA e-mail address and Git commit e-mail address matches.
  • E-mail address is not shared by other JIRA users.

The Git Integration add-on supports smart commit by adding a simple syntax to a commit message.

The basic syntax for a Smart Commit message is:

<ISSUE_KEY> <ignored text> #<command> <optional command_params>
fyi
To know more about syntax, commands and examples on Smart Commits, see Processing JIRA Software Issues with Smart Commit Messagesopen in new tab at the Atlassian website.

Basic Examples

There are Smart Commits commands that you can use in your commit messages.  Refer to the following table for more details on each smart commit command:

Command Usage and Description
#comment
The #comment command will add a comment to a JIRA issue.
Syntax:
ISSUE_KEY #comment <your comment text>
Examples:
GIT-264 #comment Resolved conflicts.
GIT-1720 #comment Plugin version change from 2.8.2 to 2.8.3. Build number change from 69 to 70.
The above examples will add the specified comment text against the JIRA issues.
warning
The committers’ email address in the git configuration must match with the email address of the corresponding JIRA user (or vice versa) to comment on issues.
#time
The #time command will record time tracking information against a JIRA issue.
Syntax:
ISSUE_KEY #time [Some amount in JIRA time syntax] <Your worklog comment text>
Examples:
GIT-264 #time 1w 6d 13h 52m Total work logged.
GIT-1720 #time 1h 20m Merged to master. Released to marketplace.
The above examples will add the respective time and worklog comment text against the JIRA issues.
warning
The JIRA time tracking feature allows users to log the length of time spent working on issues.  JIRA administrators must have enabled this feature for this smart commit to work.
#<transition-name>
The #<transition-name> command will move the JIRA issue to a particular workflow state.
Syntax:
ISSUE_KEY #<transition-name> <Your comment text>
Examples:
GIT-264 #code-review For review.
GIT-1720 #close Tasks completed. Closing ticket.
The above examples will transition the JIRA issues to their specified workflow state and add the comment to the respective JIRA issues.
warning
The JIRA user must have the appropriate project permissions to be able to transition issues.
#assign

INTRODUCED v2.9.7
The #assign command will assign the particular issue to the specified JIRA user.
Syntax:
ISSUE_KEY #assign [<JIRA username> or <email of JIRA user>]
Examples:
GIT-1925 #assign johnsmith
GIT-1961 #assign jsmith@example.com
#fixversion

INTRODUCED v2.9.7
The #fixversion command will add a Fix Version/s details tag to the specified issue.
Syntax:
ISSUE_KEY #fixversion [project version]
Examples:
GIT-1628 #fixversion 2.9.6
Adds fix version tag 2.9.6 to the issue, GIT-1628.
GIT-1628 #fixversion 2.9.5 #fixversion 2.9.6
Adds fix version tags 2.9.5 and 2.9.6 to the issue, GIT-1628.
FYI
If there was an initial Fix Version tag on the specified issue, a #fixversion command will append the new Fix Version tag to it.
For example:
The Fix Version tag, 2.9.4, already exists in issue GIT-1254.  Performing a smart commit – GIT-1254 #fixversion 2.9.5 will give a result of:

Fix Version/s: 2.9.4, 2.9.5
#affectsversion

INTRODUCED v2.9.7
The #affectsversion command will add an Affect Version/s details tag to the specified issue.
Syntax:
ISSUE_KEY #affectsversion [project version]
Examples:
GIT-1582 #affectsversion 2.9.6

note
The #affectsversion command works the same way as #fixversion.  However, it appends Affect Version/s tag instead to the specified issue.

Advanced Examples

Usage and Description
A single action on a single issue.
Example:
TEST-100 #time 2w 1d 4h 30m This is a time log comment
Records the specified worklog #time of 2 weeks, 1 day, 4 hours and 30 minutes and adds worklog comment "This is a time log comment" to the issue, TEST-100.
Multiple actions on a single issue.
Example:
TEST-100 #time 4h 30m Fix null pointers #comment Fixed code #resolve
Logs specified #time of 4 hours and 30 minutes and add worklog comment "Fixed null pointers" to the issue, TEST-100; adds the #comment "Fixed code" and resolves the issue.
A single action on multiple issues.
Example:
TEST-100 TEST-101 TEST-102 #resolve
Resolves specified issues.
Multiple actions on multiple issues.
Example:
TEST-100 TEST-101 TEST-102 #resolve  #time 2d 4h #comment Fixed code
Resolves specified issues; logs specified #time of 2 days and 4 hours and adds #comment "Fixed code" against the issues.

Starting v2.6.33 of the Git Integration for JIRA, support for multi-line commit messages for Smart Commits has been implemented. The following examples show correct usage of the Smart Commit message:

TST-1 implemented feature 1
TST-1 #comment some comment
in JIRA
on several lines
TST-1 #resolve
TST-2 #time 1h 30m
In this example, an issue key that is present on every line is a valid multi-line commit message.
TST-1 implemented feature 1
#comment some comment
in JIRA
on several lines
#resolve TST-2
#time 1h 30m
This is the equivalent smart commit message based from the above example.
TEST-3 Background color of settings should be lighter
TEST-3 #in-progress #time 1h TEST-4 resolve
TEST-2 #resolve
This example, containing several issue keys, is also a valid multi-line smart commit message.

Workflow Transitions

The simple JIRA workflow does not contain explicit transition names.  These kind of workflow with no explicit transition names are becoming more popular as Atlassian is suggesting them to administrators upon project creation.

JIRA simple workflow

The name of the status is the transition.  So, for the example above, the valid transitions from DONE are:

  • #to-do
  • #in-progress
  • #in-review
warning
Workflow transition names must be unique.
helpful tip
When there are no transition names — just use the status names.  If there is a space, replace it with "–" (hyphens).  For example, CODE REVIEW becomes #code-review.

Viewing Workflow

warning
Accessing the View workflow link on the Issue page requires a user or user group to have the View Read-Only Workflow project permissions.

You can see the available custom workflow transition commands for use with Smart Commits by doing the following:

  1. Open an issue and click View Workflow from the context of the issue (near the issue’s Status).
  2. Hover a status.
  3. When you hover a status - it will highlight available transitions.  This is the transition name that is used in Smart Commits and not the status name.

    JIRA workflow transition hover status

Below is an example using the above workflow where the issue is in OPEN status and want to send it to BUSINESS SPEC status:

<ISSUE_KEY> #to-business-spec or,
<ISSUE_KEY> #to-business and even,
<ISSUE_KEY> #to> (yes, this works, as long as it does not conflict with another transition name)

If a smart commit fails, an email notification is sent to either the JIRA user, or to the Git user if a JIRA user can't be identified.

Smart Commits Helper

The smart commit helper is introduced in v2.9.3 of the Git add-on and is available at the following locations:

  • Issue > Commit Tab
  • Project Page > Git Commits
  • Repository Browser > Commits

A smart commit helper indicator is displayed to the right of the user/commit author:

Smart commits helper example
Status Description
COMMIT The Smart Commits setting is enabled for the repository but there is no smart commit keyword in the commit message.
SMART COMMIT The commit message has a valid smart commit structure and was successfully processed.
SMART COMMIT ERROR There was an error during smart commit processing.  For example, invalid keyword; commit author and JIRA user are not the same; permission issues or wrong values.

The smart commit helper status are not shown:

  • for any smart commits that were made before Git add-on v2.9.3.
  • for smart commits that were ignored due to Smart Commits setting for that repository is disabled.
  • for smart commits that have not been processed yet.
  • for processed commits with ticket ID but without smart commit keyword when Smart Commits setting is disabled for that repository.
fyi
When Smart Commits setting is disabled for that repository, the Git add-on will not show the COMMIT indicators.

Refer to the commit message case examples below:

Commit ID Commit Message
Commit1
Merged to master
(This commit message does not contain an issue key)
Commit2
TST-1 Merged to master
(This commit message has an issue key but no smart commit keyword)
Commit3
TST-1 Merged to master #done
(This commit message have an issue key and valid smart commit keyword)
Commit4
TST-1 Merged to master #unknownSCkeyword
(This commit message has an invalid smart commit keyword)

When Smart Commits setting was set to ENABLED:

Commit ID Status after SC=Disabled Status after SC=Enabled
Commit1 Commit is ignored since issue key is not provided. Commit is ignored since issue key is not provided.
Commit2 No status indicator. COMMIT
Commit3 SMART COMMIT SMART COMMIT
Commit4 SMART COMMIT ERROR SMART COMMIT ERROR

When Smart Commits setting was set to DISABLED:

Commit ID Status after SC=Disabled Status after SC=Enabled
Commit1 Commit is ignored since issue key is not provided. Commit is ignored since issue key is not provided.
Commit2 No status indicator. No status indicator because it was marked as ignored.
Commit3 No status indicator. No status indicator because it was marked as ignored.
Commit4 No status indicator. No status indicator because it was marked as ignored.
note
The commit status shown on the Issue page depends on the Smart Commits setting that was set at the time the commits were processed.

Repository Browser

The Repository Browser allows users to view git repositories of configured projects via the Git menu on the JIRA dashboard.

fyi
As of version 2.5+ of the Git Add-on, the Git dropdown menu is added to the dashboard.
warning
Users must have the View Development Tools project permission in order to gain access to the Repository Browser. For more information on assigning JIRA permissions, see Managing Permissions in JIRA open in new tab.
note
The Git dropdown header is hidden for all users if there are no repositories with Repository Browser enabled for that user.  The Git add-on will always show the Git header to JIRA administrators.
The Git dropdown header is visible to other users who have repositories with Repository Browser enabled and have no history of using the Repository Browser (for example - no previously viewed or favorited repositores).

To view all repositories, select Git dropdown in the dashboard menu then View all repositories.

Repository Browser git menu

Available git repositories of configured projects are displayed:

  • Clicking Manage Repositories at the top right of the screen will open the git add-on repositories page.
  • Click a git repository to browse its contents.
  • In repository view, clicking Repositories at the top right of the screen will open the git add-on repositories page.
  • Select a branch from the dropdown list to browse repository contents for that branch (default view is master branch).
  • Click a folder to view its contents. Click a file to view its code diff.
  • Click on an issue link under Commit message to view that ticket.
  • Click on the commit id Latest commit: UUID link to view code diff for that commit.
  • Click on an item link under Latest commit column to view code diff for that particular commit.
note
With v2.6.0 of the Git add-on, revisions of the commits are displayed on the Repository Browser in addition to branches and tags. See Repository Browser - Commits tab, for further information.
warning
If the selected path is a root of the repository and no files are present, a message will be displayed instead of an empty file list.
helpful tip
Administrators can turn off the repository browser via advanced settings of a repository in the add-on configuration.
fyi
The displayed repositories can be sorted by clicking the corresponding list header.  The add-on will remember the sorting choice per user.

Viewing List of Commits via Repository Browser

In the Repository Browser, click the Commits tab.

The list of commits for the currently selected project is displayed in decending order:

  • Select a branch from the dropdown list to browse commits for that branch (default view is master branch).  The branches and tags are sorted in reverse alphanumeric order putting the latest tags and branches at the top of the list.
  • Click on an issue link to view that ticket.
  • Click on a commit id commit ID to view commit information and code diffs related to that commit.

Comparing Branches/Tags in the Repository Browser

In the Repository Browser, click the Compare page tab.

On this page, two branches from the current repository can be compared.  The Git add-on will show the commit of the first found branch on this screen.

A diff between the base branch and the compare branch is displayed:

Repository Browser compare commit screen

To view interesting results, use the following selection scenarios:

  • select master as base; select the most recent branch as compare.
  • select master as base; select a tag with a version release.
  • select different branches as base and compare. (Example: TYT-212 against TYT-316)

Click to swap the base and the compare selection.

The Summary page displays the Commits, Aggregated Lines by Developers and Files.  Click on a file to view its code diff.

Click Commits on the sidebar to view the list of commits resulting from this compare.  The adjacent figure indicates the number of commits associated to this compare.

Click Diff on the sidebar to view code diffs of the selected range of commits with the path and name of the affected files.

Click Issues on the sidebar to view list of unique JIRA issues related to commits. Introduced v2.10.0

On the Issues page, clicking the View all XX issues with JQL text label will open the Search page with passed query of a list of JIRA issues found based from the compare criteria. Introduced v2.10.0
For example, the JQL will look like issuekey in (GIT-1851, GIT-1159, GITCL-284, GITCL-254).

Enable/Disable Repository Browser via Repository Configuration

Go to  cog Administration  > Add-ons  >  Git Integration Plugin for JIRA  > Git Repositories.

helpful tip
If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Git Repositories.

Click  cog  Actions > Edit  to modify required repository settings.  The Advanced setup screen for configuring repositories is displayed.

Scroll down to the Repository Browser option.

Repository Browser configuration

Select Enabled to activate this function for this repository. Choose Disabled to deactivate this function from this repository.

Add one or more existing projects to associate to this git repository in the Associate Project Permissions field, in order to have Git Commits tab appear on the Issue screens of the specified projects.

Checking the Associate with all projects box will hide the existing associated projects in the Associate Project Permissions field and disable it. All existing associated projects in that field are still retained.

Click Update to save configuration changes for this repository.

Viewing Commit Code Diffs

Access the commit code diff dialog via the following:

  • View a file on the Repository Browser (Git > View All Repositories).
  • On the Compare results screen of the Repository Browser, click a file on the Summary page.
  • Go to Administration > Projects.  Select a project.  Select the Overview tab then click Git Commits.  Click a file on a commit or click View full commit.
  • Open an issue.  Select the Git Roll Up tab then click a file under Files.
  • Open an issue.  Select the Git Commits tab then click a file or click View full commit.
View commit code diffs

Each click on the expanders # lines hidden label expands up to 20 lines of code on that section.

Git User Identity

A git user can identify himself on his local computer using the following commands:

$ git config --global user.name "John Doe"
$ git config --global user.email 

Or, for specific repository:

$ git config user.name "John Doe"
$ git config user.email 

Then every commit is supported by the configured user information.

Hosting services (like GitHub and BitBucket, for example) try to match these data in commits with a particular account:

  • If the email is unknown, it just displays the name from the commit.  If there is no JIRA user associated with the email, the Git add-on will use the author's name from the commit and displays this name without any associated links.
  • Git user identity email unknown
  • If an email is configured in the local repository, the account is detected and will be displayed. The Git add-on will use the email from a commit and will search for a JIRA user using this email.  If the JIRA user is found, the associated link to his JIRA profile is displayed with the accompanying JIRA avatar beside the name.
  • Git user identity email known

JIRA User Information Card

As of v2.6.5 of the Git add-on, the JIRA user card is available on the following screens:

  • Git Commits tab (Commit author name)
  • Repositories list (Last updated by)
  • Repository Browser (under Latest commit column)
  • Code diff dialog (Commit info)

Hover the mouse pointer on the name of the user.  A small information box containing information such as email, zone & time and avatar for that user will appear.

Click Activity to view the latest activities performed by that user.

Click More > to open more options such as:

  • view this user’s profile,
  • view unresolved issues currently assigned to this user, or
  • go to the administration section for this user.
note
The Git User Identity should be configured for the specific user.  Otherwise, the user card information will not be displayed for that user.

JIRA Issue Page

If the Git add-on is configured and licensed successfully, new tabs are added to each JIRA issue.

Git Roll Up

Open an issue then go to the Git Roll Up tab to view commit statistics, diffs and related issues.

Git Roll Up tab - showing commit information, aggregated lines by developers and files added/deleted

The Summary page shows statistical information of the first and last revision of the commits and the time since the last commit was made.  A summary of the files, lines and the developers who made the changes in this range of commits are also displayed.

Starting v2.9.9 of the Git add-on, the git commit compare function (Repository Browser - Compare) is added into this tab:

  • To view a compare result, set the base: and the compare: dropdown selectors with different values.
  • The repository dropdown allows switching of context between repositories.
  • To swap the base and the compare selection, click .
  • To open the context of the Git Roll Up issue tab to the Compare page in a new browser tab, click send to compare icon.
  • To view the code diff of the compare result, click Diff on the left panel.
  • To view the commit statistics and summary of changes, click Summary on the left panel.
  • To view list of unique JIRA issues related to commits, click Issues on the left panel. Introduced v2.10.0
  • Git Roll Up tab: Issues page - showing unique JIRA issues related to commits On the Issues page, clicking the View all XX issues with JQL text label will open the Search page with passed query of a list of JIRA issues found based from the compare criteria.

    For example, the JQL will look like issuekey in (GIT-1851, GIT-1159, GITCL-284, GITCL-254).

As of v2.10.3 of the Git Integration for JIRA add-on, the Git Roll Up issue tab will now find the best matching branch name using the JIRA issue key (ex: ABC-123) to find it. For example, if you have a branch name of v2.1-ABC-123, that branch will be auto-selected when you open the Git Roll Up issue tab.

Sort the code statistics by clicking the respective Sort button then selecting the required sorting option.

Git Roll Up Sort options

Select roll up options by clicking the respective Rollup button:

Git Roll Up - RollUp options
helpful tip
To view the code diff of the file, click the corresponding  filename on the Files summary table. A dialog will appear displaying the file diff between the first and last revisions of the commit.

Git Commits

Git Commits tabs

Open an issue then go to the Git Commits tab to view commit information:

Information Description
Repository/Indexed Name of the repository (as in add-on config) and date of last synchronization with remote repo.
Author/Committer User who performed the commit. Hover the mouse pointer on the name to view user card.
Issue key This is the JIRA issue with the corresponding commit message.
Repository Name This is the name of the repository the commit has been made.  Click to browse this repository via Repository Browser.
Branch Name of the Git branch.  Click to view this branch via Repository Browser.
Commit UID UID of the commit and git host link.  Click the UID to view the code diffs for this commit.  Click the git host link to view this commit via the git host server.
Files Changed List of files affected by the commit.  Click the file or git host link to view code diff of this commit.
helpful tip
View the whole commit code diff information by clicking the View full commit button to the right of the commit message.
View code diff information of the particular file by clicking the filename for each file adjacent to the rollup counter markers.

Git Notes

Starting v2.6.21, the Git add-on displays git notes in the Git Commits tab:

Actual git commit sample, git note

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 add-on 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.

fyi
Git notes are sorted by name.

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.
fyi
For old commits that are already indexed and have issue key(s) in commit message - see FAQ > Reindex > How do I clear the Git Integration Plugin for JIRA cache manually? topic.

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/*

Code Syntax Highlighter

As of v2.5.5 of the Git Add-on, the code diff dialog view is improved.  The Git add-on uses the correct syntax highlighting when viewing the code diff of the file based on its file extension:

File Extension Language ID
css CSS
js Javascript
cpp C++
cs C#
sh Bash
java Java
sql SQL
py Phyton
rb Ruby
php, phtml, php3, php4, php5 PHP
html, html, xhtml, xml Markup
c, h, m, mm, pl, pm CLike
fyi
There is no language auto-detection in the diff dialog.  The detection is based on file extension.
warning
This feature will only display properly on browsers supported by Atlassian for specific versions of JIRA:

JIRA Project Page

The Project page allows you to manage project related options.

All Versions

History of commits can also be viewed within the whole project scope. To do this, select a project then click the Git Commits tab. The format of commits is similar to that on the issue page.

Project tab Git Commits
helpful tip
  • To view commit code diff information, click the View full commit button to the right of the commit message.
  • To view code diff information of the particular file, click the filename for each file adjacent to the rollup counter markers.
  • Click on the issue name of the commit to open it with the Repository Browser. Related commits for that issue name are displayed.
  • Click on a commit ID to open it with the Repository Browser. Related issues and commits for that GUID are displayed.
fyi
The Git Commits tab displays a notification when no commits are present.
warning
If Repository Browser setting is disabled for that project, the user will not be able to view files for commit from any repositories associated with that project.

Commits for Select Version

Project tab Release versions

Commits can also be limited using a particular revision. Revision and commits are connected using the logic below:

  1. All issues linked with particular revision are selected (using both ‘fix version’ and ‘affects version’ fields).
  2. Commits linked with these tickets are fetched.

JIRA Developer Panel

Git links are now available on the developer panel in the following screens:

  • Issue page
  • Search page in detailed view
  • JIRA Agile screen
JIRA Git Source Code panel

The 236 commits refers to an existing Git Commits view, which the issue tab have now.  Clicking this text link will reload the page and automatically selects the Git Commits tab to view the commits.

The Roll Up refers to an existing Git Roll Up view, which the issue tab have now.  Clicking this link will reload the page and automatically selects the Git Roll Up tab to view the git code summary.

Click on the clone repo Clone Repository text link to open the Git Repository Connection Information dialog.

The Branches section lists the branches names, linking the selected branch to view via the Repository Browser.  Only unmerged branches are shown here.

In Issue and Search pages, the developer panel is visible on the right pane:

Dev panel search and issue pages

In JIRA Agile screen, click on an issue on the board grid.  Scroll down on the right pane to view the developer panel:

JIRA developer panel Agile screen

The numbers ahead and behind represent the number of commits that are ahead/behind the main branch:

  • Ahead  –  number of commits in the branch which are not merged to the master.
  • Behind  –  number of commits in the master which are not merged to the branch.

Clicking on the branch text links will open that issue in the Repository Browser.  If Repository Browser is disabled for this repository, the text links will be inactive.

note
The Branches section is only visible if commits from this branch are not merged to master.  It's also not displayed if the repository is not associated with a project.
warning
If the user does not have the View Development Tools project permission for the project, the developer panel will be unavailable for that user.

Git Tags

Git tags identify specific release versions of your code in a particular branch and do not change when the branch moves on.  A tag is an alias for a commit hash, much like symbolic names for a given revision.  It is typically used to mark a particular point in the commit.  It is like a branch with a read-only attribute.

note
Having more than one tag with the same name across different branches can become difficult to maintain.

Tags cannot be moved since it is linked to a specific commit and are not pushed by default. 

fyi
Create a branch to start working from it if a tag is checked out.

The Git add-on supports two types of git tags:

  • lightweight  –  shows only the commit object
  • annotated  –  shows the message, author and the tag object followed by the commit

A lightweight tag can be use for marking a version or some specific commits that you will need to use later on  —  like a temporary object label.  It does not contain extra information.

Annotated tags can contain a message, author and date different than the commit that they are pointing to  —  like describing a release without making a release commit.

Starting v2.8.0, the Git Integration for JIRA add-on supports both lightweight and annotated tags.  The tags are loaded separately from the rest of the Git Source Code.

The git tag is displayed on the right sidebar if it is enabled in the General Settings of the add-on.  This feature is disabled by default for existing customers and is automatically enabled for new customers.

Git tags in Code Dev panel - right sidebar

The Git add-on will show the most recent tags if no filter is set.  If the filter is set, the Git add-on will use it and will display the tags sorted in ascending order by date.

If there are several git tags listed, click the more... label link to expand the list in increments of five tags.

note
Git tags and branches are cached for the most recently viewed 1000 JIRA issues (across all JIRA projects).  The cache is reset each time a new change in any repository is detected.  The cache is built the first time an issue with a tag and/or branch is loaded by a user.  Thus, subsequent loading of JIRA issues with tag or branch information will utilized cached values.

Move the mouse pointer over the tag to display the following tooltip information:

  • Repository Name
  • Date / Time
  • Commit author name and email address (if available)
  • Message (if any)
Git tag tooltip

Reindexing

warning
You must be a member of the jira-developers group to start reindex.

Synchronization between the repository and add-on will start automatically, however, reindexing may be required to manually start the synchronization process.

There are two ways to do this:

  1. To start update of all repositories, go to the Git Integration for JIRA add-on Git Repositories tab then click Reindex All button. Once synchronization is started, the progress will be displayed on this tab.
  2. If a specific repository needs to be synchronized, click the Action cog  icon then Reindex.

Click the view see icon to see the reindex progress of the selected repository.

note
Git log entries may not immediately appear when you open Git Commits tab right after the add-on installation.  You need to wait until the revision indexer job completes the initial synchronization.
helpful tip
For advanced administrators who want to have more control on reindex, see the Git Integration for JIRA Reindex API.
fyi
As of JIRA 6.3.10, Atlassian added the Scheduler Administration (Administration > System > Scheduler Details) page.  This page displays the properties of the JIRA internal scheduler, the scheduled jobs and their triggers.
helpful tip
The Repository Reindex (GitRevisionIndexerJob) can be configured in the General Settings page of the Git add-on.

Last Indexed Revision

The add-on stores the ID of the last indexed commit for each branch. This ID is used to limit the processed data upon reindex or update. This way, only new commits will be indexed on the next synchronization.

Click the Actions cog  icon then Reset to reset the Last Indexed date. Perform this process whenever an add-on is updated or re-installed.

Reindex and updatedDate Filter

The Git Add-on automatically changes the updatedDate of an issue when a Git commit is added to an issue upon reindex. When the reindex encounters a commit previously modified by the user relating to an issue, that issue will be updated.

You can enable or disable this setting in the Git Add-on General Settings screen.

fyi
As of v2.5.16, the add-on updates the "updatedDate" field whenever a commit is made.

JQL Searching

The Git Integration for JIRA add-on has added JQL operators and fields to query JIRA using JQL and git context via the JIRA search.

The JIRA JQL has been extended as follows:

Criteria Name JQL Field Syntax Description Search Result Value Example
Git Commits Referenced
  • gitCommitsReferenced is not empty
  • gitCommitsReferenced is empty
  • True for all issues referenced by a git commit
  • True for all issues not referenced by a git commit
True or “” (empty string)
Git Branch gitBranch in (Version-5.2, Version-5.3) True for all issues referenced by a git commit in branch Version-5.2 and branch Version-5.3 Version-5.2, Version-5.3
Examples:
gitBranch in (master) AND resolution = Unresolved
gitCommitsReferenced is not empty AND resolution = Unresolved

Webhooks

Trigger immediate reindex of your repositories from remote systems via webhooks.  For more information about this topic, see About GitLab Webhooks open in new tab .

Go to  cog Administration  > Add-ons  >  Git Integration Plugin for JIRA > Web Hooks.

helpful tip
If using JIRA 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for JIRA on the sidebar, select Web Hooks.
Git Repositories reindex web hook

Enable/disable the webhook feature by clicking on the Enable webhook checkbox.

The Secret Key is a secure random-generated alphanumeric string at the time of the Git add-on installation.  The user can change this to a different value by generating another secret token according to the Git host.  Use this key in the form of <JIRA_BASE_URL>/git/webhook/reindex/<SECRET_KEY> .

fyi
All the repositories will be reindexed if the URL specified above is activated through GET, POST, or PUT and the webhooks are enabled.
There will be no authentication checking and support for other HTTP methods such as DELETE or HEAD. The body of a POST or PUT is ignored.

Example: https://your.jira.com/rest/gitplugin/webhook/1.0/reindex/sdf34tGdfgGDG345g3y0045TYG23te37

Adding Webhook for GitHub Repository

 

Configure webhook by logging in to your GitHub account:

  1. Select a repository.
  2. Go to the Settings page.
  3. Github webhook settings
  4. Select Webhooks & services.
  5. Click Add webhook.  The following page is displayed:
  6. GitHub Webhooks - Add webhook
  7. Paste the obtained Secret URL from the Git Integration for JIRA add-on  >  Webhooks page into the Payload URL field.
  8. Select the Just the push event option as triggering event.  This is the default option when creating a new webhook.
  9. Click Add webhook to save the new webhook settings.

Adding Webhook for GitLab Repository

 

Configure webhook by logging in to your GitLab account:

  1. Select a repository.
  2. Go to the settings page by clicking the cog icon, then
  3. Select Webhooks.
  4. Gitlab webhooks setting
    The following page is displayed:
    GitLab Webhooks - Add webhook
  5. Paste the obtained Secret URL from the Git Integration for JIRA add-on  >  Webhooks page into the Payload URL field.
  6. Select the Push events as a triggering event option.  This is the default option when creating a new webhook.
  7. Click Add webhook to save the new webhook settings.

JIRA High Availability and Clustering (Data Center compatibility)

As of v2.6.12 of the Git add-on, the Data Center version of JIRA is supported.  JIRA 6.3 or higher is required for Data Center editions of JIRA.

fyi
Known issue (admins): To provide access for both users for newly created tables, configure default tables and sequences permissions as follows (where jira1 & jira2 are users):
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL PRIVILEGES ON tables TO jira1;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL PRIVILEGES ON tables TO jira2;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL PRIVILEGES ON sequences TO jira1;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL PRIVILEGES ON sequences TO jira2;

The configured repositories are located on the shared resource, since the nodes do not contain their own copy of the repositories.

The smart commits are processed by the reindex job which run once per cluster.  The node updates the index during the scheduled reindex job.

The GarbageCollection job should be run once on one node at the same time.

Indexing triggers:

  • Indexing is run on newly created repository on other nodes.
  • Entries from index will be removed on other nodes.
  • Reindex all repositories on other nodes when the reindex job is triggered.

Localization

Starting v2.6.25 of the Git add-on, unicode characters are now supported and displayed properly.

The following language localization for this add-on are available:

  • German (starting v2.5.7)
  • Polish (starting v2.6.30)
  • French (starting v2.6.31)
  • Russian (starting v2.6.31)
  • Japanese (starting v2.6.38)
  • Chinese (starting v2.9.4)
  • Spanish (starting v2.9.9)

To switch to another language:

  1. Go to your User Profile.
  2. Under Preferences, click the pencil icon.
  3. On the Update User Preferences screen, select one of the supported language from the list.
  4. Click Update to apply the new settings.

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 is located on the same server as your JIRA service. It is cached locally for performance reasons and queried everytime the list of git commits is displayed.

Lucene indexes

Lucene is an index service within your JIRA instance. It ships with JIRA and Git Integration for JIRA also makes use of it. The add-on 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 in the JIRA services configuration screen).

For every configured repository, this process do the following:

  • Updates the local clone of repository
  • Updates the lucene indexes with commits added recently
note
Due to the async structure of the add-on, commits that have been registered with index become visible after the revision indexer job has been executed. To show commits immediately, you have to start the reindex manually.

Licensing Notice

The Git Integration for JIRA add-on contains some code that covers this license:

Copyright (c) 2013, Atlassian Pty Ltd
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice,
    this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.