logo flat Git Integration for JIRA. See Git commits in JIRA.

Welcome Git Admin!

You are probably reading this page because a JIRA administrator has requested access to the Git server.  The JIRA administrator has installed the Git Integration for JIRA add-on.


What is the Git Integration for JIRA add-on?

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

JIRA users will be able to securely browse content in Git without requiring you to create IDs for every user.


How does JIRA interact with the Git server?

The Git Integration for JIRA add-on acts as a regular Git client.  It performs a scheduled pull from the repository.


What does the JIRA administrator need?

The JIRA administrator needs the ability to clone the repository and pull from it just like a regular developer workstation would do.

We recommend that you create a new user identity specifically for this JIRA server.

For Git repositories with HTTP/HTTPS access

Please do the following:

  1. Create a new user for the JIRA server.
  2. Send the JIRA administrator:
  • The URL to the Git server
  • For example:  https://gitserver/repo/timetrackingproject.git
  • The username and password for the user you created

For Git repositories with SSH access

Please do the following:

  1. Define a new SSH public/private key pair for the JIRA server
  2. Install the public key on the Git server
  3. Send the JIRA administrator:
  • The URL to the Git server
  • For example:  git@gitserver:repo/timetrackingproject.git
  • The private key you created

For Git repositories with Git protocol access

Send the JIRA administrator the URL to the Git server.

For example:  git://gitserver/repo/timetrackingproject.git

For Git repositories on the same host as JIRA

Send the JIRA administrator the full path to the Git repository.

For example:  /home/git/repo/timetrackingproject.git

For Git repositories across network file shares

If you have users access the Git repository over a network file share using Windows file sharing or NFS, the network share will need to be mounted on the JIRA server.  Assist the JIRA administrator in mounting the network share.  Then, provide the JIRA administrator with the path to the Git repository over the network share.

Linux example: /mnt/gitserver/home/git/repo/timetracking.git

Windows example: \\gitserver\git\repo\timetracking.git

For Git repositories hosted on Windows servers

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.

The repository setting for Enable Fetches of the configured network path must be Git Repository hosted on same server as JIRA.

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.

Restart JIRA to regain access to repositories.


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

Considering the above conditions, verify if the repository can be cloned successfully using the network path.  With the server which hosts JIRA, start the command-line session under the same user which JIRA is running on.

For example:

$ git clone file:////Ws148/Photo/repo
Cloning into ‘network-repo’...

If the path is invalid, does not exist or has permission issues, an error similar to the following will be displayed:

fatal: '//Ws148/Photo/repo' does not appear to be a git repository
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

For more information, see Documentation: Adding a Repository Hosted on Windows Servers or Windows Network Share open in new tab .


Setting Up 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.

Does the Git Integration for JIRA add-on have API commands that allow addition/removal of a Git project?

Yes.  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 Integration for JIRA: Hook and API Reference - Repository REST API open in new tab.


Reindex API to Trigger Indexing

Call the Reindex REST API to have more control on indexing.

Reindex POST API
Use this method to start the reindex process in a separate thread.
Example:  http://jira.yourorg.com/rest/gitplugin/1.0/index.json
Reindex GET API
Use this method to track messages for a particular thread.
Example:
http://jira.yourorg.com/rest/gitplugin/1.0/index.json?threadId=eafe58fc-d8de-42ff-8815-6fe5860b38d2

For more information, see Git Integration for JIRA: Reindex REST API open in new tab .


Reindex Interval

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.

General Configuration Repository Reindex Interval

Set the automatic reindex interval frequency value in minutes as required.  The default value is 5 minutes.  Min = 1, Max = 2147483647.

Regardless of the time to index, the reindex interval is the amount of time between the currently completed reindex task until the next reindex.

Improving JIRA performance depends on the duration value of the RevisionIndexJob.  To see the Last run duration value:

  1. Go to Administration > System.
  2. On the sidebar, select Scheduler details.
  3. Scroll to com.xiplink.jira.git.revisions.RevisionIndexJob.
  4. Scroll to RevisionIndexJob last run time
  5. Click Show more under the Actions column.
  6. Show RevisionIndexJob last run time

If the Last run duration value shows 3 minutes or greater, we recommend to increase the reindex interval.

The reindex interval must be greater or equal to the Last run duration value of RevisionIndexJob to improve JIRA performance.  For example, if the Last run duration value is 20 minutes, set the Reindex interval value to 20 minutes or more in the Git add-on General page.


Web Linking

The web linking feature adds links to your git hosting provider directly into the Git Commits tab.

helpful tip
Configure web linking options while adding/editing repository settings so that commits can include links to the git host pages.

 

Configure Web Linking for GitHub/GitLab

 

For more information, see Documentation: Web Linking open in new tab .


Webhooks

Trigger immediate reindex of your repositories from remote systems via webhooks.

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 General.

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 your Git host.

Use this key in the form of <JIRA_BASE_URL>/git/webhook/reindex/<SECRET_KEY>

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

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 .  Hence, the body of a  POST  or  PUT  is ignored.

fyi
The Git Integration for JIRA add-on supports GitHub and GitLab push events to define individual repository to index.

 

Adding Webhook for GitHub Repository

 

Adding Webhook for GitLab Repository

 

For more information, see Documentation: Webhooks open in new tab .


Improving Git Tags Performance

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.  Subsequent loading of JIRA issues with tag or branch information will utilize cached values.

Enabling the display of Git tags in commits for large repositories can affect the performance of JIRA.  This setting can be disabled by doing the following steps:

  1. Go to JIRA Administration > Applications. (JIRA 6.x – Administration > Add-ons)
  2. On your sidebar under Git Integration for JIRA, select General.
  3. Look for the Git Tags setting and uncheck it.
  4. Click Save to save and apply the setting.

Improving Diff Load Performance

There's a default limit to the size of files that the diff'er supports which is 16MB.  This is to keep a massive file from impacting the JIRA server performance too much.

As of v2.8.5 of the Git add-on, JIRA administrators can control over the size of diffs allowed to be displayed in the code diff dialog:

  1. Go the Administration > Applications.
  2. Under Git Integration for JIRA on the sidebar, select General.
  3. Scroll down to Diff then set the Max Diff Line Count value as desired.  Maximum supported value is 20000.
  4. General Settings Diff Limit
 

Do note that setting this value higher than the default value will impact the performance when loading the code diff of the selected file in the Git Commits tab.  The code diff dialog will truncate the view for each 1500 lines code.  To see the rest of the code, manually expand the view.


Increasing Timeout Threshold for Large Repositories while Doing a Git Pull

For this workaround to work, the user must have an access to a JIRA hosting instance:

  1. Login to the hosting server.
  2. Create a new directory in the path different from the JIRA HOME directory.  For example, ~/Image-repo/
  3. Go to a directory and perform a clone of a repository:
  4. git clone --mirror git@gitserver.com:repo/url.git1

    Or use the generic clone:

    git clone git@gitserver.com:repo/url.git2
    1 Modify the git repository URL to the correct one.
    2 Using the generic clone may take a bit longer and requires more disk space to store.
  5. For ~/Image-repo/ directory, give read and write permissions to the same user running JIRA.
  6. For example, to make the user named user be an owner of a folder, perform the following command:

    sudo chown user ~/Image-repo
  7. Using the local path, connect the repository via the Git Integration for JIRA add-on Advanced setup wizard.  Use the correct local path for the Git add-on to successfully detect the repository.
  8. Connect git repositories advanced setup screen about adding and detecting local repository
  9. Click Detect to specify the origin value.
  10. Configure other settings if required. Click Add to proceed.

The repository is added and indexing should work.

helpful tip
If you have several large repositories and have a problem with exceeded timeout, we recommend that you use our Tracked Folders feature to scan local folders at once and import repositories automatically.

Git Integration for JIRA Add-on Upgrade with Minimal Risk

helpful tip
For full list of features, version history and supported JIRA version of the Git for JIRA add-on, see Git Integration for JIRA add-on Version History.

If you have installed the Git Integration for JIRA add-on with versions prior to v2.10.2, perform the following steps to upgrade with minimal risk:

  1. Do the upgrade at night – when the number of JIRA users is minimal.
  2. Make backups.
    1. Make a JIRA backup (recommended).  The Git for JIRA add-on upgrade only updates its components.  Thus, it has no adverse effect to JIRA.  It is still better to make a backup of your JIRA before any add-on upgrade as a safety measure.
    2. Make a Git add-on backup (recommended). Make sure to do a backup of the Git connection configuration.
      1. Perform a bulk export of your existing repositories in the Git add-on repositories configuration.  (Go to Administration > Add-ons/Applications > Git Repositories > Bulk Change > Export Configuration.  For detailed steps, see Bulk Change > Export Configuration.)
      2. Git add-on Bulk Export access
      3. Make sure that you have all the required SSH keys uploaded to the Git for JIRA add-on  (Go to Administration > Add-ons/Application > SSH Keys).  This will make seamless connection of the git repositories to JIRA via Bulk Change > Import Configuration.
      4. Git add-on upload SSH keys access
  3. Upgrade the Git for JIRA add-on to the latest version.
helpful tip
If you have several large repositories and have a problem with exceeded timeout, we recommend that you use our Tracked Folders feature to scan local folders at once and import repositories automatically.

Another option is to completely uninstall then reinstall the Git for JIRA add-on.  This will result in JIRA running on a clean state:

  1. Backup the Git repositories configuration via the Git add-on Bulk Export.
  2. Fully uninstall the Git Integration for JIRA add-on  –   follow these instructions.
  3. Install the Git Integration for JIRA add-on via UPM.
  4. Add all required SSH keys again by uploading them into Git for JIRA add-on > SSH keys.
  5. Using the file from Bulk Export, import all your repositories via Bulk Change > Import Configuration.
  6. Manually reindex the repositories based on its usage priority or click Reindex all to reindex them all at once.
Get new product notifications and feature updates from BigBrassBand LLC.
Need to know more features?  Read further at  Git Integration for JIRA add-on Documentation