Get started guide for Jira administrator

Get started guide for Jigit - Jira GitHub & GitLab integration for Jira On-Premise administrators.

About Jigit

Jigit is a Jira application for Jira On-Premises (Server and Data Center) that provides an issue view tab, which displays all commits and pull/merge requests referencing the issue key from connected Git systems like GitHub, GitLab, and Gerrit Code Review.

The development panel displays issue-related branches, permits the creation of new feature branches, pull or merge requests, mapping branches to the Jira issue directly from the issue view screen.

Jigit gives you a convenient way to collect commits and pull requests from GitLab and GitHub. Jigit queries Git servers using their public REST APIs and saves commits and pull requests into a Jira database, so no code access is required. The app uses only the commit history.

The App does not have access to your source code. It doesn't clone your repositories, so no disk space is used to store sources. It uses REST APIs to query data.

Jigit Plugin Configuration

To start the Jigit plugin configuration for integration with GitHub, GitLab, Gerrit platformsusing multiple ways - Access tokens, OAuth apps, Basic Auth, etc.

How to generate Personal Access Token in GitHub?

How to generate Access Token in GitLab?

Once your Access Token is ready, you can move to the integration set-up.

First of all, you have to add a new configuration on the Global configuration page:

Move to the Jira Administration section (“gear” button in the right corner of the navigation menu).
Navigate to the Manage app page and find our application Jigit Plugin Config on the left sidebar.
On the Global Configuration page, navigate to the Jigit Plugin Configuration tab.
Click on Add in the bottom right corner and create a new configuration. After specifying all the necessary parameters, click the Ok button to save it.
The Test Connection button lets you check the connection and communication between Jira and the linked GitHub or GitLab instances.

Below you can find a short definition of each parameter you have to specify in the modal window that appears in front of you:

Parameter	Definition
`Alias`	indicate an alias/name for your configuration which will be displayed on the commits tab page; an alias should be unique; you can't add two configurations with the same alias.
`Host`	enter a host of your Git server; it can be https://github.com, or https://gitlab.com, or your instance on the GitLab server (for example, https://my.own.gitlab:8443). Also, you can create a GitHub app and use it to get access to Github, the app needs to have the necessary permissions. Important: After you change GitHub app permissions you need to make sure it was reinstalled on the organization level and the permission-change was accepted by the organization admin/owner.
`Access Token`	authentication token you created before that allows an individual user to authenticate and access GitHub resources. Service accounts are often used for this purpose.
`Path`	path; it can be either a repository name or a repository group (GitLab) or organisation (GitHub) name; a repository name usually consists of two parts and is displayed in the query string of a browser. For example, in the URL https://gitlab.com/gitlab-org/gitlab-ce the name of the repo is gitlab-org/gitlab-ce and the group name is gitlab-org. Also you have to specify content type inside a given path: repository or a group of repositories (drop-down opposite the path) To include all repositories in a group you need to use `.` mask. Subgroups are only working with GitLab*.
`Default Branch`	The default branch of your GitHub or GitLab repository that will be used for integration with Jira, by default it is indicated `master` branch; Jigit indexes git commits from the default branch and then from the others. When you use Test Connection action, it uses the default branch and the first accessible repository to check the connectivity.
`Index`	a way of branch indexing: all branches inside a repository; selected branches; branch mask helps filter and match specific branches in your GitHub or GitLab repository. The aim is to decrease the number of API calls if this number is limited (it's actually for https://github.com, for example). If you select the "all branches" option, Jigit makes API calls to check whether there have been new git commits since the last check (even to stale branches).
`Jira Projects`	Jira project names list where the commits and pull requests should be visible
`Commit indexing window`	a time period within which commits are indexed and associated with Jira issues
`Commit request timeout`	the maximum amount of time allowed for making a request to retrieve commit information from the connected GitHub or GitLab repository; this parameter is used when Jigit calls the git server by HTTP API, and if the timeout is exceeded during a call the add-on stops the indexing of a repository. If you see ConnectException: Connection timed out in JIRA logs, you can increase this value to overcome it. Default and recommended - 10 seconds.
`Sleep`	the duration of a pause or delay between consecutive requests made by the integration to the connected GitHub or GitLab repository Default and recommended - 10 seconds.
`each`	frequency at which the integration checks for new commits or changes in the connected GitHub or GitLab repository Default and recommended - 100 requests.
`Enable smart commits`	Available since 3.04.01 allows you to enable or disable the use of smart commits; Jigit support for smart commits for transition: if you write the commit message in the form #in-progress (hash, status name without spaces), the issue will be transitioned to the status In Progress. The smart commits work similarly to the Bitbucket Smart Commits. It works only if your workflow does not have any mandatory fields on transition.
`Ignore smart commits older than`	lets you to specify a time duration after which smart commits should be ignored
`Add git activities as issue comments`	when enabled, Git activities, such as commits, pushes, and merges, are automatically added as comments to associated Jira issues. After a commit is added, the operation can't be reversed. Comment stays there even if plugin is deleted.
`Index pull requests`	Available since 4.12.19 Jigit can index, pull and merge request messages; when this parameter is enabled, the integration will actively monitor and index the pull requests in your repositories. The pull or merge request title should contain the issue key. For instance, DEV-123 added support for pull requests indexing for GitLab and GitHub.
`Display repos in the development panel`	the visibility of repositories to be able сreate a branch, link a branch to Jira issue, and сreate a code review using Jigit Development Panel.

Here is a quick demo video of connecting Jira to GitLab using the Jigit app.

Once the configuration has been created, you can start using the app on the Jira issue view screen. The other configurations are optional to make your integrations more streamlined and efficient.

Global settings

The Global Settings tab allows Jira administrators to configure and customize the integration settings. Those settings include:

Jira project selector;
URL pattern editor to restrict the URL where the Jigit can connect;
checkbox to enable non-ASCII symbol removal.

After specifying the necessary parameters, click the Ok button to save configurations.

Below is a short definition of each parameter of the Global Settings tab.

Parameter	Definition
`Projects to show Jigit Tab`	Jira projects where the Jigit Tab is visible No projects chosen means available everywhere.
`Projects to hide Jigit Tab`	Jira projects where the Jigit Tab is not visible No projects chosen means available everywhere.
`URL pattern`	allows you to define the URL to which the Jigit can connect; by default, all URLs are allowed, but the Jira administrator can use `jira-jigit-plugin.url.pattern` environment variable to set the URL pattern, which restricts the URL entered for all new configurations. For example, -Djira-jigit-plugin.url.pattern="https://github.com\|https://gitlab.com".
`Remove non-ASCII symbols from commits and pull requests`	ensures that any non-ASCII symbols or characters in commit messages and pull request titles are removed or replaced with ASCII equivalents. It is required for some DB engines that do not handle non-ASCII characters. Non-ASCII symbols refer to characters that are outside the standard ASCII character set, which includes characters such as letters, numbers, and basic punctuation marks commonly used in the English language. Examples of non-ASCII symbols include special characters, diacritical marks, emojis, or characters from other languages and scripts.

Gerrit Code Review

Jigit - Jira GitHub & GitLab integration supports integration with Gerrit Code Review, allowing you to link Gerrit changesets and reviews with your Jira issues. This enables you to seamlessly bridge the gap between code reviews and project management in Jira. When the Gerrit is integrated with Jira using Jigit, it shows the data in a separate Jira issue view tab.

Configuration

To configure Gerrit Code Review navigate to the Gerrit tab on the Global configuration page and enable the integration.

Since version 6.15.04 multiple instances of Gerrit Code Review tool are supported.

Create a new configuration rule following the next steps:

Click the Add button in the bottom right corner of the Configuration tab.
After you have specified all the necessary parameters click on the Ok button to save the new rule.
The Test Connection button allows you to check the connection and communication between Jigit and the connected Gerrit Core Review account.

Please, read the definitions of each parameter you have to specify in the modal window that appeared in front of you:

Parameter	Definition
`Name`	the name of your configuration rule
`Enabled`	refers to whether the integration with Gerrit Code Review is enabled or disabled
`URL`	URL to Gerrit Server instance allows the Jigit app to connect to your Gerrit and retrieve information about changesets, reviews, and other related data.
`User`	username or account that the Jigit app will use to authenticate and interact with your Gerrit to access the REST APIs
`Password`	the password or authentication token associated with the user account specified in the "User" setting
`Gerrit Project`	the specific project or repository in your Gerrit instance that you want to integrate with Jigit app. Here you can restrict search results only to particular Gerrit Project. This parameter is optional. No projects are chosen means that the app will search for all changes in Gerrit.
`Use only for Development panel`	restricts the Jigit plugin to only be used within the Development panel of Jira
`Add Gerrit development panel`	display status information into the development panel on the Jira issue view screen
`Projects to hide Gerrit`	the list of Jira projects where to hide Gerrit information
`Projects to show Gerrit`	the list of Jira projects where to show Gerrit information
`Search for issue in`	the list of items where to search for the Jira issue key mentioned
`Hashtags`	the Gerrit changes with the given hashtags appear first in the result. Hashtags might increase amount of request to get the changes.
`Monitoring window`	the time interval during which Jigit will actively monitor and retrieve updates from the Gerrit

Hashtags

How to see Gerrit high priority code reviews in the Jigit Development panel

Circuit Breaker

With the circuit breaker, you can make Jira more stable when Gerrit is unavailable or having issues. The circuit breaker monitors the connectivity and responsiveness of integrated services such as Jira, GitHub, and GitLab. It keeps track of the success or failure rate of requests made to these services.

Below are the parameters' definitions that help you tweak the circuit breaker according to your system. We recommend starting with the default ones before your start tweaking those.

Parameter	Definition
`Failure rate threshold`	percent of failures to stop querying Gerrit
`Monitoring window`	period in seconds during which requests are monitored
`Minimum requests`	minimum requests to calculate state
`Slow request threshold`	requests which are longer than interval are treated as slow
`Slow requests rate threshold`	percent of slow requests to stop querying Gerrit
`Silence interval`	if problems are detected than plugin stops querying Gerrit for target interval

Gerrit JQL functions

In Jigit - Jira GitHub & GitLab integration, the JQL (Jira Query Language) function is available for filtering changes in Gerrit. Jigit leverages the Gerrit REST API to interact with Gerrit and perform JQL-based queries.

This function is experimental and may cause the performance issues if used with unbound scope. Please provide your feedback.

Gerrit performance

Gerrit information is queried when the Jira issue is rendered, and the data is placed in the Cache. Default cache invalidation is 3 minutes; it is configurable.
Gerrit information is not stored in the Jira database and lives only in the memory in Jira Cache.
Gerrit integration uses ETags to cache the results. The current cache configuration is 1000 items of each size of up to 5MB.

Available since 5.07.27/6.07.27

Jigit Development Panel

Available since 5.02.23

Jigit Development Panel is a panel on the issue view screen where you can see related branches and create a new branch in the configured git connections. The Jigit Development Panel provides information about branches and pull requests whose names include the issue key.

For this feature to work you need to make sure the access token used in the configuration has the right permissions to do the create-branch operation.

To configure the Jigit Development Panel displaying, you need to:

Navigate to the Jigit Development tab on the Global Configuration page.
Enable the displaying with the checkbox help.
Additionally, you can provide Patterns of repositories to show and Patterns of repositories to hide, allowing you to specify repository patterns that determine which repositories are displayed or hidden in the Jigit Development Panel.
Click on the OK button to save configurations.

To be able to сreate a branch, link a branch to Jira issue, and сreate a code review using Jigit Development Panel you need to enable parameter Display repos in the development panel during Jigit Plugin Configuration.

Please watch this demo video for more details about the Jigit Development panel.

Require user PAT

Jira administrators can configure Jigit to use the user’s PAT instead of admin-configured PAT.

Admin can control this in the global settings (since version 8.08.22).

The Jira end-users will need to visit their personal settings and configure PATs.

The benefits of having users configured PATs are:

increased security, the users can only see what they see in the Git system
spread the load on GitHub using different PATs. Git systems usually have limits of API calls per PAT, the more PATs are used, the better.

How-tos

How-To Guides

Debugging and troubleshooting

Please follow this how-to article - How to enable debug-level logging for Jigit: Jira GitHub GitLab integration?

Updated: 04 Sep 2023