Skip to main content
If you want to run Kody with a github app, you need to create a GitHub App. This app enables Kody to interact with your repositories, manage pull requests, and receive webhooks.
If you want to enable “Sign in with GitHub” for platform users, that’s a separate OAuth App process and doesn’t interfere with the GitHub App permissions. This guide focuses on the functional integration.

​
Prerequisites

Have your application domains ready:
  • WEB_DOMAIN: Your Frontend URL (e.g., https://app.yourdomain.com or http://localhost:3000)
  • API_DOMAIN: Your Backend/API URL (e.g., https://api.yourdomain.com or http://localhost:3000 for monorepo/proxy setups)

​
Step 1: Create the GitHub App

  1. On GitHub, go to Settings > Developer Settings > GitHub Apps
  2. Click New GitHub App
  3. Fill in the basic information (Name, Homepage URL) according to your preference

​
Step 2: Configure Callback and Setup URLs

GitHub App Webhook This step is critical to ensure installation and redirection work properly. Fill in the fields below, replacing WEB_DOMAIN with your actual URL:
  • Callback URL: 
    WEB_DOMAIN/api/auth/callback/github
    This URL is used to complete the authorization flow.
  • Setup URL: 
    WEB_DOMAIN/setup/github
  • Check the option: Redirect on update This ensures that after installing the app, users are redirected back to Kodus to complete the setup.

​
Step 3: Configure the Webhook

The webhook notifies Kodus about events in your pull requests.
  • Webhook URL: 
    API_DOMAIN/github/webhook
  • Make sure the Active option is checked

​
Step 4: Collect Credentials and Add to .env

GitHub App Webhook Now you need to get the credentials generated by GitHub and add them to your Kodus environment variables.

​
App ID

At the top of your app’s “About” page, copy the App ID. Add to your .env: 
API_GITHUB_APP_ID=your_app_id_here

​
Client Secret

Go to the Client secrets section and click Generate a new client secret. Copy the generated value. Add to your .env: 
API_GITHUB_CLIENT_SECRET=your_client_secret_here

​
Private Key

Scroll to the bottom of the page and click Generate a private key. This will download a .pem file. Open this file with a text editor and copy the entire content. Add to your .env: 
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."

​
Summary of Environment Variables

At the end, your configuration file should contain: 
API_GITHUB_APP_ID=123456
API_GITHUB_CLIENT_SECRET=example_secret_123
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."
Click Save Changes on GitHub and restart your Kodus application to apply the changes.