• Products
  • Documentation
  • Resources

Manually create a GitHub app for Enterprise Server

If you’re using GitHub Enterprise Server (version 2.18 or lower), the instructions on this page will help you manually create an app to connect your GitHub account with Jira Software.

If you're using GitHub Enterprise Server on version 2.19 or higher, you can create an app automatically when you connect Jira with GitHub.

Create a new app in GitHub

Once you’ve installed the GitHub for Jira app and selected a server to connect, Jira will prompt you to create an app in GitHub.

  1. In Jira, select Manual app creation.

  2. Open the GitHub Enterprise website in a new tab and log in to your Enterprise Server account.

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

  4. Select GitHub Apps and then New GitHub App.

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

  6. Create a homepage URL by combining your domain and app name in the following structure: http(s)://<your-domain>/apps/<your-github-app-name

Copy URLs from Jira to GitHub

Next, copy the URLs from your Jira manual app creation page to GitHub:

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

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

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

  4. Create a Webhook secret phrase.

    1. This is optional in GitHub, but it's needed for Jira to listen to and process webhook events. It can be something random, like 'jirarocks’.

Grant permissions in GitHub

To allow Jira to listen to webhook events and populate development data from GitHub, you need to add permissions and event subscriptions.

  1. Add the following repository permissions:

    1. Actions (read-only)

    2. Contents (read & write)

    3. Deployments (read-only)

    4. Issues (read & write)

    5. Metadata (read-only, mandatory)

    6. Pull requests (read & write)

  2. Add the following organizational permission:

    1. Members (read-only)

  3. Select the following event subscriptions:

    1. Security advisory

    2. Commit comment

    3. Create

    4. Delete

    5. Deployment status

    6. Issue comment

    7. Issues

    8. Pull request

    9. Pull request review

    10. Push

    11. Repository

    12. Workflow run

‘Read & write’ permissions are optional, but the ‘create branch’ feature will not function without them.

Submit app details in GitHub

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

  2. Select Create GitHub App to save and submit your app.

Copy app details from GitHub to Jira

Finally, copy the app details from GitHub to your Jira manual app creation page:

  1. Copy the App ID and Client ID fields and paste them into their fields in Jira.

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

  3. Select Generate a private key to download a pem file. Upload the file to the Private key field in Jira.

  4. Make sure the GitHub app name and Webhook secret fields are the same across GitHub and Jira.

    1. To view your webhook secret in GitHub, select Edit.

 

Additional Help