Git Integration for Jira Self-Managed (Data Center/Server) Documentation

Contact Support

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 ( 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.


You must be an organization owner or have admin permissions in a repository to install/uninstall a GitHub App on an organization. If a GitHub App is installed in a repository and requires organization permissions, the organization owner must approve the application.

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.

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:

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

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

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

  4. Pick the integration that conforms to your configuration:

    • 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 password 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

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

Have feedback about this article? Did we miss something? Let us know!
On this page