Get started guide for Jigit - Jira GitHub & GitLab integration for Jira On-Premise administrators.
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.
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:
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.
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.
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; 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
Subgroups are only working with GitLab.
The default branch of your GitHub or GitLab repository that will be used for integration with Jira, by default it is indicated
When you use Test Connection action, it uses the default branch and the first accessible repository to check the connectivity.
a way of branch indexing:
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 project names list where the commits and pull requests should be visible
a time period within which commits are indexed and associated with Jira issues
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.
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.
frequency at which the integration checks for new commits or changes in the connected GitHub or GitLab repository
Default and recommended - 100 requests.
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.
lets you to specify a time duration after which smart commits should be ignored
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.
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.
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.
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.
Jira projects where the Jigit Tab is visible
No projects chosen means available everywhere.
Jira projects where the Jigit Tab is not visible
No projects chosen means available everywhere.
allows you to define the URL to which the Jigit can connect; by default, all URLs are allowed, but the Jira administrator can use
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.
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:
the name of your configuration rule
refers to whether the integration with Gerrit Code Review is enabled or disabled
URL to Gerrit Server instance allows the Jigit app to connect to your Gerrit and retrieve information about changesets, reviews, and other related data.
username or account that the Jigit app will use to authenticate and interact with your Gerrit to access the REST APIs
the password or authentication token associated with the user account specified in the "User" setting
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.
restricts the Jigit plugin to only be used within the Development panel of Jira
display status information into the development panel on the Jira issue view screen
the list of Jira projects where to hide Gerrit information
the list of Jira projects where to show Gerrit information
the list of items where to search for the Jira issue key mentioned
the Gerrit changes with the given hashtags appear first in the result. Hashtags might increase amount of request to get the changes.
the time interval during which Jigit will actively monitor and retrieve updates from the Gerrit
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.
percent of failures to stop querying Gerrit
period in seconds during which requests are monitored
minimum requests to calculate state
requests which are longer than interval are treated as slow
percent of slow requests to stop querying Gerrit
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 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 showand
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.
Debugging and troubleshooting
Please follow this how-to article - How to enable debug-level logging for Jigit: Jira GitHub GitLab integration?