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:
-
GitHub App (GitHub.com and GitHub Enterprise Cloud)
-
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:
-
On your GitHub web portal, go to your organization ➜ Settings tab.
-
On the sidebar, click Developer settings ➜ GitHub Apps.
Integrate to a GitHub App
As an initial configuration requirement, admins need to install the GHA in an organization. After this setup, only then Jira can read the repositories with Git Integration for Jira app:
-
On your Jira dashboard menu, go to Git ➜ Manage repositories.
-
On the Add new integration panel, click GitHub.
-
With version 4.6, the GitHub App integration feature is added to the External service list.
-
Pick the integration that conforms to your configuration:
-
GitHub.com and GitHub Enterprise Cloud
-
GitHub Enterprise Server
-
-
Enter Organization name.
For GHA on GitHub Enterprise Server external service, enter Host URL and Organization name.
-
Click Connect to continue.
-
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.
-
Click Connect to start configuring this GitHub App integration.
The Git Integration for Jira app will perform this task automatically. Provide password credentials if prompted. -
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)
-
Click Create GitHub App… to proceed.
-
Choose:
-
All repositories – to connect all repositories from this organization.
-
Only select repositories – lets you select a specific repository for this setup.
-
-
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 gijsupport@gitkraken.com
-
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
Troubleshooting GHA integrations
A GHA integration may get stuck in INSTALLING status. At the moment, we found three cases when it may happen:
| Case | What happened | What the user can do to remove the integration |
|---|---|---|
| 1 | The integration is waiting for response from a GitHub server | Wait till the GitHub server responds |
| 2 | The GHA was not installed during connecting of the integration | Install the GHA and then remove the integration as usual |
| 3 | The GHA was removed from the GitHub server | Nothing |
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.
