Private GitHub (OAuth 2.0) Apps

Overview

GitHub Apps are tools that extend GitHub's functionality. GitHub Apps can do things on GitHub like open issues, comment on pull requests, and manage projects. They can also do things outside of GitHub based on events that happen on GitHub. For example, a GitHub App can post on Slack when an issue is opened on GitHub.

This connection mode does not require a preexisting AutoKitteh server-wide configuration. Instead, it allows project owners to configure the details of their own apps.

If you want to use the AutoKitteh server's default GitHub app, see the Default App guide.

If you want to use a Personal Access Token (PAT) and/or a personal webhook, see the PAT + Webhook guide.

NOTES

Only organization and repository owners can install GitHub apps.

This guide assumes that the AutoKitteh server is already configured with HTTP tunneling.

GitHub Documentation

Background information: about using GitHub apps.

Create a GitHub App

Depending on your preference, use one of these options:

• The app will be owned by you, i.e. a GitHub user:
  https://github.com/settings/apps/new

• The app will be owned by a GitHub organization:
  https://github.com/organizations/ORG-NAME/settings/apps/new
  (This requires GitHub organization owner privileges)

tip

If you want the GitHub app to be private, create it in the same GitHub user/organization scope where you intend to install it. If you want multiple GitHub users and organization to install it, create a public GitHub app.

You will make this choice in step 7 below.

1. Required details:

   • GitHub App name
   • Homepage URL

2. Identifying and authorizing users:

   • Callback URL:

     • AutoKitteh public cloud: https://api.autokitteh.cloud/oauth/redirect/github
     • Dedicated environments: https://NAME-api.autokitteh.cloud/oauth/redirect/github
       (where NAME is the AutoKitteh server's name)
     • Self-hosted servers: https://PUBLIC-ADDRESS/oauth/redirect/github
       (where PUBLIC-ADDRESS is the public tunnel address)

   • Expire user authorization tokens: No

   • Request user authorization (OAuth) during installation: Yes

     

3. Post installation:

   • Redirect on update: Yes

     

4. Webhook:

   • Active: Yes (default)

   • Webhook URL:

     • AutoKitteh public cloud: https://api.autokitteh.cloud/github/webhook
     • Dedicated environments: https://NAME-api.autokitteh.cloud/github/webhook
       (where NAME is the AutoKitteh server's name)
     • Self-hosted servers: https://PUBLIC-ADDRESS/github/webhook
       (where PUBLIC-ADDRESS is the public tunnel address)

   • Webhook Secret: random and secret string of your choice

     

5. Permissions:

   Your choices in this section depend on a balance between functional and security needs, which GitHub API calls you expect AutoKitteh scripts to make, and which GitHub API events you expect AutoKitteh scripts to respond to.

   ATTENTION

   Permission changes have to be accepted by owners of existing installations before they become effective.

   Some common repository permission examples:

   • Actions
   • Administration
   • Commit statuses
   • Contents
   • Issues
   • Metadata (mandatory)
   • Pull requests

   Some common organization permission examples:

   • API insights
   • GitHub Copilot Business
   • Members

   See also this comprehensive guide: permissions for GitHub apps.

6. Subscribe to events:

   Your choices in this section depend on the chosen permissions above, and which GitHub API events you expect AutoKitteh scripts to respond to.

   Some common examples:

   • Meta
   • Commit comment
   • Issue comment
   • Issues
   • Pull request
   • Pull request review
   • Pull request review comment
   • Pull request review thread
   • Push
   • Release
   • Repository
   • Status
   • Workflow dispatch
   • Workflow job
   • Workflow run
   • Sub issues

7. Where can this GitHub App be installed?

   Choose one of these options:

   • Only on this account (only the GitHub user/org that created this GitHub app)
   • Any account (any GitHub user or organization)

8. Click the green button "Create GitHub App"

App Details

1. Copy the App ID and Client ID strings at the top of the app settings page

   

2. Click the button "Generate a new client secret", and copy the new string; you will not be able to see it again once you leave this page

   

3. Double-check that the webhook secret was indeed set when you created the app; if it's not, set it again, and click the green "Save changes" button

   

4. Click the "Generate a private key" button at the bottom of the app settings page

   
   • This will auto-download a file named APP-NAME.DATE.private-key.pem

AutoKitteh Connections

When you create, initialize, or edit the connection in an AutoKitteh project:

1. Select the "GitHub" connection type, if not selected yet

2. Select the "Private GitHub app" authentication type, if not selected yet

3. Enter the app details from the previous section:

   • App ID (required)
   • App name (required)
   • Client ID (required)
   • Client secret (required, readbale only when re/generated)
   • Webhook secret (required, readable only when re/set)
   • Private key (required, downloadable only when re/generated)

4. If your organization uses a GitHub Enterprise Server (GHES), enter its URL in order to replace the default https://github.com

5. Click the "Start OAuth Flow" button