Manually create a GitHub App

If you want to connect a GitHub Enterprise Server account to Jira Software, you must create an app in your GitHub instance. Creating an app can be done automatically or manually. This page has instructions on how to create an app manually.

Getting started

1. Log in to your GitHub Enterprise Server account.

2. Navigate to http(s)://<your-domain>/settings/apps. This will take you to your developer settings. You can also navigate to these settings by clicking on your profile picture in the top-right and selecting User settings > Developer settings.

3. On the Developer settings page, select GitHub Apps in the left panel and then select New GitHub App.

Register a new GitHub App in GitHub

Create a GitHub App name

Enter a name for your app. You can choose any name you like, but it must be unique to your server.

Next, you can add a description for your app - this step is optional.

Create a homepage URL

Create a URL for the homepage input by subbing your domain and app name into the following structure:

http(s)://<domain>/apps/<github-app-name>

Your input in this field should look something like this:

Once your app is created, this homepage URL should take you to the homepage of your GitHub App.

Find your manual app creation URLs in Jira

Next, you’ll need to copy several URLs from your manual app creation page in Jira and paste them into the app creation form in GitHub.

Copy the callback URL

1. Copy the URL from the User authorization callback URL field in Jira. It will look something like this: http(s)://<domain>/github/callback/<id>.

2. Paste this URL into the Callback URL field in GitHub.

Copy the setup URL

1. Copy the URL from the Setup URL field in Jira. It will look something like this: http(s)://<domain>/github/setup/<id>.

2. Paste this URL into the Setup URL field in GitHub.

Copy the webhook URL and add a secret

1. Copy the URL from the Webhook URL field in Jira. It will look something like this: http(s)://<domain>/github/events/<id>.

2. Paste this URL into the Webhook URL field in GitHub.

3. Add a webhook secret. GitHub lists this as an optional field, but it’s required for Jira to listen to and process webhook events - so you must enter something to successfully complete your integration. You could provide a randomly generated string or add something simple like “mycompanyisawesome”.

Specify your permissions in GitHub

You need to give permissions at a repository and organization level in GitHub, and you must subscribe to events. These permissions and subscriptions allow Jira to listen to events from GitHub so that we can populate your Jira project with development data.

Repository permissions

Add the following repository permissions:

• Actions: read-only

• Contents: read-only

• Deployments: read-only

• Issues: read & write

• Metadata: read-only (GitHub mandatory permission)

• Pull requests: read & write

Organizational permissions

Add the following organizational permissions:

• Members: read-only

Subscribe to events

Select the following event subscriptions:

• Security advisory

• Commit comment

• Create

• Delete

• Deployment status

• Issue comment

• Issues

• Pull request

• Pull request review

• Push

• Repository

• Workflow run

Submit GitHub App details

After you’ve reviewed all the fields in your form, select Create GitHub App to save. You must complete this step before moving on to the next section.

Complete the “Manual app creation” page in Jira

Once you've successfully created your app in GitHub, you must complete the manual app creation page in Jira.

1. Copy the following fields from GitHub and paste them into their respective fields in the Manual app creation page in Jira:

   1. App ID

   2. Client ID

2. Select Generate a new client secret in GitHub, wait for the page to refresh, and then copy and paste this into the GitHub client secret field in Jira.

3. Select Generate a private key in GitHub to generate and automatically download a pem file. Upload this file to the Private key field in Jira.

4. Make sure that the following fields are consistent between GitHub and Jira:

   1. GitHub App name

   2. Webhook secret - this is the secret you added in GitHub when you created the app. To view this now, select Edit in the webhook secret field in GitHub and then copy the value into Jira.