Manually create a GitHub App

Manual app creation

If you're creating your GitHub app manually, you’ll be redirected to the manual app creation page. Keep it open, and go to GitHub’s website in a separate tab.

Create your app in GitHub

Log in to your GitHub Enterprise Server account.

1. Go to Developer settings at http(s)://<your-domain>/settings/apps.

2. Select GitHub Apps and then New GitHub App.

3. Give your app a unique name and add an optional description.

4. Create a Homepage URL by subbing your domain and app name into the following structure: http(s)://<your-domain>/apps/<your-github-app-name.

Copy URLs from Jira to GitHub

Next, copy URLs from the manual app creation page in Jira.

1. Copy the User Authorization Callback URL from Jira and paste it into the Callback URL field in GitHub.

2. Copy the Setup URL from Jira and paste it into the Setup URL field in GitHub.

3. Copy the Webhook URL from Jira and paste it into the Webhook URL field in GitHub.

4. Add a Webhook Secret. This field is optional in GitHub, but it's required for Jira to listen to and process webhook events. You can provide a random or simple string, like "mycompanyisawesome".
   
   

Specify your permissions and subscriptions in GitHub

To allow Jira to listen to events from GitHub and populate your project with development data, you need to grant permissions and subscribe to events at both the repository and organization levels in GitHub.

• Add the following repository permissions: Actions (read-only), Contents (read & write), Deployments (read-only), Issues (read & write), Metadata (read-only, mandatory), Pull requests (read & write). Note: Write permissions are optional, but without them, the create branch feature will not function.

• Add the following organizational permission: Members (read-only).

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

Submit GitHub app details

1. Review all the fields in your GitHub app form.

2. Click Create GitHub App to save and move to the final step in Jira.

Fill in the manual app creation page in Jira

Copy the App ID and Client ID fields from GitHub and paste them into their respective fields in Jira.

1. In GitHub, select Generate a new client secret, wait for the page to refresh, and then copy and paste the secret into the GitHub client secret field in Jira.

2. In GitHub, select Generate a private key to download a pem file. Upload this file to the Private key field in Jira.

3. Ensure the GitHub app name and Webhook secret fields are consistent between GitHub and Jira. To view your webhook secret, select Edit in the webhook secret field in GitHub and copy the value into Jira.