GitHub App integration

GitHub offers a variety of integration options, including: API, OAuth, and more recently GitHub Apps. There are a number of benefits to using GitHub app over OAuth:

• GitHub apps are by nature an organization installation. A separate GitHub account or service user is not required.

• Because GitHub apps require GitHub administrator authorization, we can rely on the GitHub app having administrator permissions.

• Determine repository access at the organization or repository level for the integration

• GitHub apps have a higher rate limit than OAuth.

For more details, see the GitHub Apps article.

New integration options

Two new integration options are added into the Add new integration wizard Connect screen:

1. GitHub App (GitHub.com and GitHub Enterprise Cloud)

2. GitHub Enterprise App (GitHub Enterprise Server)

There are two terms:

• GitHub Application (GHA) – GHA itself is a set of authorization information. It is created in some GitHub organization during the first step of connecting a GHA integration with the Git Integration for Jira app.

• Installation of a GitHub Application – To get access to repositories inside the organization, an admin has to install the GHA in the organization. During the installation of GHA, the administrator selects the scope that will be available for this installation of this GHA. It is the second step of connecting a GHA integration.

Permissions

Check GitHub Apps permission for your organization:

1. On your GitHub web portal, go to your organization ➜ Settings tab.

2. On the sidebar, click Developer settings ➜ GitHub Apps.

Pre-requisites

IMPORTANT!

• As an initial configuration requirement, admins need to install the GHA in an organization. After this setup, only then that Jira instance can read the repositories with Git Integration for Jira app.

• Establishing a connection using GHA is a two-way process. This requires the Jira instance, where the GHA integration is connected, be accessible remotely from the GitHub server. Make the IP of the Jira instance accessible from the internet as well as add this IP address to the GitHub.com allow list.

Limitations

• Only one GHA installation is allowed on each GitHub organization. This is because the GHA itself is created each time on the first step of connecting a GHA integration and prevents the reuse of an existing GHA for installing in another organization.

• The Cancel function on the scope selection page does not do anything and GIJ have no control and cannot affect its behavior. When a user installs a GHA created manually, clicking Cancel redirects back to the GHA page.

• We advise users against renaming their GHAs. GIJ uses this name for identifying the GHA. However, the GitHub server does not return information about the application rename event. Thus, GIJ has no way to receive any information about the new name. As the result, the your GitHub app link on the Remove integration page will return a 404 page error if a GHA is renamed.

Integrate to a GitHub App

1. On your Jira dashboard menu, go to Git ➜ Manage repositories.

   
   

2. On the Add new integration panel, click GitHub.

3. With GIJ version 4.6+ and later, the GitHub App integration feature is added to the External service list.

   
   

4. Pick the integration that conforms to your configuration:

   • GitHub.com and GitHub Enterprise Cloud

   • GitHub Enterprise Server

5. Enter Organization name.

   
   

   For GHA on GitHub Enterprise Server external service, enter Host URL and Organization name.

6. Click Connect to continue.

   
   

7. On the Settings screen, the Require user PAT setting is enabled and cannot be changed because it is directly affected by the Enforce Git service permissions setting in the General settings page. For the GHA feature, the user’s PAT is not mandatory since it can interact with the Git server using the GHA access token.

8. Click Connect to start configuring this GitHub App integration.

   The Git Integration for Jira app will perform this task automatically. Provide login credentials if prompted.

9. On the following screen, enter a descriptive name for the new GitHub App. (Changing this name later on will have a negative impact on the GHA integration)

   
   

10. Click Create GitHub App… to proceed.

    
    

11. Choose:

    • All repositories – to connect all repositories from this organization.

    • Only select repositories – lets you select a specific repository for this setup.

12. Click Install to complete this process.

The GitHub App integration is now displayed in the Git repositories configuration list.

Post-install notes

The GHA is created automatically by Git Integration for Jira app. For any related questions, please contact [email protected]

• You can reconfigure connected repositories in the Edit integration connection settings page for this GHA integration ( Actions).

  
  

• Make sure that the following properties must not be changed for this GHA integration:

  • GitHub App name
  • Post installation
  • Webhook attributes
  • Private keys
  • Any settings on the Permissions and Events page
  • Any settings on the installation page

• Admins can restrict repositories using the JMESpath filter to avoid a case when a user tries to connect thousands of heavy repositories resulting in decreased Jira performance.

• A GHA installation can be suspended in two ways:

  • From the owner side — Press Suspend on the Integration Connection settings for the selected integration via GIJ actions. RECOMMENDED
  • From the user side — Press Suspend on the GitHub portal for the GHA installation. NOT RECOMMENDED

• It is possible to re-issue a PEM key for a GHA on the GitHub server side. However, the only way to update the PEM key of a connected GHA integration is via Bulk Import. Bulk export the GHA integration and then paste the entire PEM key enclosed in double quotes into the .tsv file (to preserve line esc chars).

• A GHA must be deleted by its owner. If several users have access to Repository Management, only one of them can actually remove the app from the Git server after the GHA integration is removed.

Troubleshooting GHA integrations

A GHA integration may get stuck in INSTALLING status. At the moment, we found three cases when it may happen:

If GitHub App integration is stuck on Installing status, use the Remove integration action to remove such integration.

However, removing GHA integrations this way (in cases #1 and #2) will leave an unconnected/lost GHA on the GitHub server. As all data for connecting are stored in the integration, there is no way to connect an existing GHA to a new integration. On the other hand, the admin of the GitHub server can remove such lost GHA manually.

For case #3, while this case is very rare, the integration will remain in the Manage Git integration list. The Jira admin can remove the integration using the Remove integration action.

More Integration Guides

GitHub.com (Git Integration for Jira Data Center/Server)

GitHub Enterprise Server (Git Integration for Jira Data Center/Server)

GitHub App integration (this page)

GitLab.com (Git Integration for Jira Data Center/Server)

GitLab CE/EE (Git Integration for Jira Data Center/Server)

Azure DevOps | Visual Studio Team Services (VSTS) (Git Integration for Data Center/Jira Server)

Azure DevOps Server | Team Foundation Services (TFS) (Git Integration for Jira Data Center/Server)

AWS CodeCommit (Git Integration for Jira Data Center/Server)

Gerrit (Git Integration for Jira Data Center/Server)

Bitbucket Server (Git Integration for Jira Data Center/Server)

Bonobo (Git Integration for Jira Data Center/Server)

Windows Network | Server Share (Git Integration for Jira Data Center/Server)

Tracked Folders (Git Integration for Jira Data Center/Server)

Back to: Integration basics (Git Integration for Jira Data Center/Server)