Server Configuration

Follow this guide in order to enable AutoKitteh's GitHub connections to use a single GitHub app with OAuth 2.0, instead of connection-specific Personal Access Tokens (PATs) and/or webhooks.

note

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

Only organization and repository owners can install GitHub apps.

Create a GitHub App

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.

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)

Required Details

• GitHub App name

• Homepage URL

  

OAuth Callback URL

• Callback URL: https://PUBLIC-AK-ADDRESS/oauth/redirect/github
  (where PUBLIC-AK-ADDRESS is the AutoKitteh server's public tunnel address)

• Expire user authorization tokens: No

• Request user authorization (OAuth) during installation: Yes

  

• Post installation → redirect on update: Yes

  

Webhook

• Active: Yes (default)

• Webhook URL: https://PUBLIC-AK-ADDRESS/github/webhook
  (where PUBLIC-AK-ADDRESS is the AutoKitteh server's public tunnel address)

• Webhook Secret: random and secret string of your choice

  

Repository Permissions

Your choices in this section depend on a balance between functional needs and security constraints: 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.

Here are some common examples:

• Actions (read and write)
• Administration (read-only)
• Commit statuses (read and write)
• Contents (read-only)
• Issues (read and write)
• Metadata (read-only)
• Pull requests (read and write)

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.

Here are some common examples:

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

Where Can This 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)

Finally, click the green button "Create GitHub App".

App Secrets

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
   • Convert this file into a single-line string with this command-line:

     cat NAME.YY-MM-DD.private-key.pem | awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}'
   • Delete this file

Configure AutoKitteh

There are two equivalent options to configure the AutoKitteh server to interact with your GitHub app - choose the one most suited for your needs and constraints.

For more details, see the Configuration Methods page.

config.yaml File

Stay tuned!

Environment Variables

Set this environment variable, based on the AutoKitteh server's address - either an HTTP tunnel's public address, or an internal address in a Virtual Private Cloud (VPC):

• WEBHOOK_ADDRESS
  • Just the address, without the http[s]:// prefix, and without a path suffix

Also set this environment variable:

• GITHUB_APP_NAME
  • Based on the suffix of the app settings URL: https://github.com/.../settings/apps/APP-NAME

Also set the following environment variables, based on the values you were instructed to copy in the App Secrets section above:

• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
  • Readbale only when generated
• GITHUB_PRIVATE_KEY
  • Downloadable only when generated
  • When setting the environment variable, the value has to be enclosed in quotes (e.g. GITHUB_PRIVATE_KEY="<key>") because it contains special characters
• GITHUB_WEBHOOK_SECRET
  • Readbale only when re/set

If your organization uses a private GitHub Enterprise Server (GHES) instead of https://github.com

Set the environment variable GITHUB_ENTERPRISE_URL to the GHES URL inside your organization's VPC without a path, i.e. a string that looks like this: http[s]://host[:port].

Lastly, restart the AutoKitteh server for these settings to take effect.