Skip to main content
Skip table of contents

How to set up GitHub App integration?

GitHub App Setup

Permissions

The GitHub App requires the following permissions prior to integration:

Repository permissions:

  • Administration:
    Access: Read and write

  • Contents:
    Access: Read and write

  • Metadata:
    Access: Read-only

  • Projects:
    Access: Read-only

  • Pull requests:
    Access: Read and write

To update your GitHub Apps permissions, go to the app in your GitHub account located here, click the image-20240530-160411.png button next to your app, select image-20240530-160455.png from the menu to the left, then change the approrpiate Repository Permissions, then click the Save changes button at the bottom.

Private Key

From the image-20240530-160950.png section of your GitHub, scroll down to the Private Keys section and click to generate a private key as shown below:

image-20240530-161409.png

Once the private key has downloaded, open the file with a text editor, as the contents will need to be pasted during the integration setup.

Jigit GitHub App Integration

Navigate to the Jigit Plugin Config located under the Managed apps section of Jira. Under the Configurations Tab, select image-20240530-161835.png

  1. Select GitHub App and specify which of the apps features are required.

    image-20240530-162044.png

  2. Enter the specified details and paste the Private Key from your GitHub App and the App Id, found in the General section of your GitHub App.

    image-20240530-163904.png

  3. Select which branches to be indexed

    image-20240530-164131.png

    From the Advances settings, you can change the indexing parameters:

    image-20240530-164439.png

  4. Provide a name for the Integration

    image-20240530-164333.png

Pressing the image-20240530-164645.png will check the integration is complete, and provide an error for any issues that need to be address. Once you have a green bar with image-20240530-164846.png, press Save and the integration is complete.

Below you can find a short definition of the additional parameters you can specify:

Parameter

Definition

Select Git system to connect with

specify the Git system for your connection; Azure DevOps, GitLab, GitLab 8 or earlier, GitHub or GitHub App

Use only for Development Panel

select to prevent commits from being indexed. Development Panel on issue view screen will only display branches and pull-requests.

Index pull-requests in repositories

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 repositories in the development panel

the visibility of repositories to be able to сreate a branch, link a branch to the Jira issue, and сreate a code review using Jigit Development Panel.

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.

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.

Host

enter a host of your Git server; it can be https://github.com, https://gitlab.com, https://dev.azure.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.

Path to group/repository

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.

For Azure DevOps integration, in the URL https://dev.azure.com/Move-Work-Forward/BTR%20project/_git/MWF the name of the repo is Move-Work-Forward/BTR%20project/_git/MWF and the group name is Move-Work-Forward or Move-Work-Forward/BTR%20project.

Also, you have to specify the 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.

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.

What branches to index

a way of branch indexing:

  • All branches inside a repository

  • Branch mask helps filter and match specific branches in your GitHub or GitLab repository.

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

Jira Projects to associate configurations with

Jira project names list where the commits and pull requests should be visible

Smart commits period

lets you to specify a time duration after which smart commits should be ignored

Override indexation settings

allows you to manually change the default settings for indexation

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.

Integration name

indicate an alias/name for your configuration which will be displayed on the configurations tab page; an alias should be unique; you can't add two configurations with the same alias.

Enable

enables the configuration to allow indexation

Updated:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close