Jira GitHub and Gitlab integration
Jigit is an application for Jira Server or Data Center that provides an issue tab, which displays information about all commits and pull requests referencing to the issue key. Additionally, it provides related JQL functions.
You can find Github, Gitlab Jira integration at Atlassian Marketplace.
About Jigit
Jigit is a Jira application for Jira On-Premises (Server and Data Center) that provides an issue tab, which displays information about all commits referencing the issue key. For instance, a commit has “DEV-345 added integration tests“, and this message will appear in the issue view for DEV-345. Additionally, you can display the pull request information as well.
Jira and GitHub/GitLab integration give you a convenient way to collect commits and pull requests from GitLab and GitHub. It has minimal settings: all you need to start is to provide a server name, a repository name and a personal access token. No additional settings at GitHub or GitLab are required. Jigit queries Git servers using their public REST APIs and saves commits into a Jira database. There is no access needed. The App only uses the commit history.
Additionally, Jigit provides a development panel on the Issue View screen where a person can see the issue-related branches and create a new branch directly from the source code.
Gerrit Code Review tool is supported as well.
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.
End-user guide
Configuration
Log in to JIRA as an administrator.
Choose the Settings menu (cog icon on the top right).
Choose the Manage apps menu.
Click on the Jigit Plugin Config link to get into the configuration page.
Quick video demo
Below is a quick demo of how to connect Jira to GitLab using the Jigit Jira App by Move Work Forward.
Jigit Development panel video demo
Security & Architecture explained
Jigit - Security & Architecture
The data stored by this App
Frequently Asked Questions
You can Jira GitHub and GitLab integration frequently asked questions guide here.
How to add a new repository or a group of repositories
Go to the configuration page and click the Add button in the bottom right corner.
Enter the following information:
Enter an alias for your repo. This name will be displayed on the commits tab page. The alias should be unique; you can't add two repositories with the same alias.
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
Enter the access token following the instructions from the section below.
Key in a Path. It can be either a repository name or a group(in terms of GitLab)\organisation(in terms of 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.
To include all repositories in a group you need to use .* mask.
Specify content inside a given Path: a group of repositories or a single repo.
Important: Subgroups are only working with Gitlab.
You can also define the Jira project list where the commits and pull requests should be visible.
Repository pattern: if you use a
groupconfiguration type, you can define the repository pattern to reduce the number of scanned repositories.
All other data is additional:
Select a way of branch indexing: all branches inside a repository or only selected branches. 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).
Default branch name. First, Jigit indexes git commits from the default branch and then from the others.
Commit request timeout. This parameter is used when Jigit calls the git server by HTTP API. If the timeout is exceeded during a call, then the add-on stops the indexing of a repository. If you see a ConnectException: Connection timed out in JIRA logs, you can increase this value to overcome it.
Sleep timeout and several request parameters prevent Jigit from excessively using the server's API. By default, Jigit sleeps for ten seconds for every hundred commits.
Using a GitHub.com token
Navigate to your Personal settings → Developer settings → Personal access tokens → Fine-grained tokens.
Pick the Resource owner - usually it is an organization.
Give the name to the token and select the required minimal repository-level permissions.
Contents: Read and write.
Metadata: Read-only
Pull requests: Read and write.
Set the expiration date and press the Generate token button.
Copy the token and paste it into the Access Token field in Jigit.
Using a GitHub application
If you are using the Jigit Development panel to create feature branches and view the related to the issue pull requests you need to make sure the following permissions are also added to the scope:
Pull requests - read permission (to list the PRs)
Content - write permission (to create a feature branch)
Important: After you change GitHub app permissions you need to make sure it was reinstall on the organization level and the permission-change was accepted by the organization admin/owner.
You can create a GitHub application and use it to get access to Github.
The application needs to have the following permissions.
Jigit Development Panel
Quick demo video - https://www.youtube.com/watch?v=0cntVk4K0cA
Since version 5.02.23 Jigit has added a Development Panel to the Issue View screen where you can see related branches and create a new branch in the configured git connections.
For this feature to work you need to make sure the access token used in the configuration has the right permissions to do create-branch operation.
The Jigit Development Panel provides information about branches and pull requests that have in the name the issue key. For instance, below you can see the pull requests for the issue key TEST-10.
Gerrit Code Review support
Gerrit Code Review integration with Jira can be done with Jigit. You need to follow this separate guide to learn more.
Performance-related parameters
Jigit - Performance considerations
Create an access token
GitHub access token: Read here about how to create an access token in GitHub. Note, that Jigit uses only repo scope to read commits. If a user sees a Not Found error, you need to make sure that the path to the repo is correct AND the token has the correct scope.
GitLab access token: GitLab provides options to use GitLab project access token Or GitLab personal access token you can find information about how to create an access token in GitLab. Jigit uses only API scope to read commits' information.
Order of branch indexing
As mentioned above, at first, Jigit indexes commits from the default branch (usually, master). This means that if a commit to a branch has been merged to the default branch before the start of the indexing, then it will be indexed as a commit to the default branch. The add-on starts indexing all other branches in a lexicographical order after indexing the default branch. I.e. at first, it will index the default branch, then branch develop and then branch feature-123.
How to add a new branch to be indexed
If you only index concrete branches, go to the configuration page. Key in a branch name in the Branches column of a row with the configuration of the target repo.
JQL functions
Jigit adds the following Jira Query Language functions.
issuesWithCommitCount(number) - is the JQL function that narrows down the Jira issue search result by limiting the number of commits associated with an issue.
Gerrit-related JQL functions are here.
If you need any other functions related to the Gitlab or GitHub commits please contact us.
Commit message
If you want a git commit displayed on an issue tab, you should specify the issue key in the commit message. For E.g. make a commit with the message "fixes TST-123: a new implementation of hashCode", where TST-123 is the issue key. Message can contain more than one issue key; in this case, a commit will be displayed on the tab of every mentioned issue.
The app does NOT have a mapping between Github/Gitlab and Jira users, but to add the comment, we need to specify the user on which behalf we add the comment. We use Assignee or the Creator(if the issue is not assigned) as the comment author.
GitHub/Gitlab user is specified in the comment itself
Smart commits
Since version 3.04.01, Jigit has supported smart commits for transitions. If you write the commit message in the form #in-progress (hash, no spaces and dashes are important), the issue will be transitioned to the status In Progress. The smart commits work similarly to the Bitbucket Smart Commits.
Pull and merge requests
Since version 4.12.19, Jigit can index, pull and merge request messages. There is a new setting in each configuration rule Index pull requests.
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.
Settings
Project whitelist and blacklist
In the global settings, it is possible to select projects where the Jigit Tab is visible (whitelist, no projects means - available everywhere). There is a list of the projects to hide in the Jigit Tab as well - no projects means - available everywhere.
Restrict the URL where the Jigit can connect with
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 rules.
For instance, -Djira-jigit-plugin.url.pattern="https://github.com|https://gitlab.com".
Debugging
If you need to debug the app, please add jigit with the DEBUG log level in the Jira logging section and reproduce the issue you are having. Please send us the support zip afterwards.
Proposals
Leave your feature proposals here.
Feedback
We'll be grateful if you leave feedback.
Updated: