> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a GitHub App

> Create the GitHub App that lets Kody read your repositories, comment on pull requests, and receive webhooks — with the exact permissions to grant.

If you want to run Kody with a GitHub App, you need to create one. This app enables Kody to interact with your repositories, manage pull requests, and receive webhooks.

<Note>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. See <a href="/en/how_to_deploy/platforms/github/github_oauth">GitHub OAuth App</a>.</Note>

## 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)
* **WEBHOOK\_DOMAIN** (optional): Public domain for webhooks (e.g., `https://kodus-webhooks.yourdomain.com`). If you route `/.../webhook` on the API domain, you can use `API_DOMAIN`.

## 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

<img src="https://success.skyhighsecurity.com/@api/deki/files/66490/Click_newGithubApp.png?revision=1" alt="GitHub Apps settings page highlighting the New GitHub App button" />

## Step 2: Configure Callback and Setup URLs

<img src="https://kodus.io/wp-content/uploads/2026/01/githuapp-urls.gif" alt="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.

<Note>
  Webhooks are handled by a separate service (port 3332). If you use the API domain here, ensure your reverse proxy routes `/github/webhook` to the webhooks service. Otherwise use a dedicated webhooks domain.
</Note>

* **Webhook URL**:
  ```
  WEBHOOK_DOMAIN/github/webhook
  ```

* Make sure the **Active** option is checked

## Configure repository permissions and events

Under **Repository permissions**, configure the following access for the enabled features. Do not leave all permissions at **No access**.

| Permission    | Access         |
| ------------- | -------------- |
| Contents      | Read-only      |
| Pull requests | Read and write |
| Issues        | Read and write |
| Checks        | Read and write |
| Metadata      | Read-only      |

Contents write access is only needed for features that commit repository files; read-only is sufficient for reading code. Install the app on the intended repositories and approve any newly requested permissions on existing installations.

Subscribe to **Pull request**, **Pull request review comment**, **Issue comment**, and **Push**. The current webhook handler accepts these four event types; other events may return 200 while being ignored.

## Step 4: Collect Credentials and Add to .env

<img src="https://kodus.io/wp-content/uploads/2026/01/gthubapp-env.gif" alt="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----- ..."
```

### Installation URL

Open your GitHub App and click **Install App**. Copy the URL from the browser address bar (it looks like `https://github.com/apps/<app-slug>/installations/new`).

Add to your `.env`:

```
WEB_GITHUB_INSTALL_URL="https://github.com/apps/your-app/installations/new"
```

## Summary of Environment Variables

At the end, your configuration file should contain:

```bash theme={null}
API_GITHUB_APP_ID=123456
API_GITHUB_CLIENT_SECRET=example_secret_123
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."
WEB_GITHUB_INSTALL_URL="https://github.com/apps/your-app/installations/new"
```

Click **Save Changes** on GitHub and restart your Kodus application to apply the changes.

## Verify the connection

The webhook URL must reach the webhooks service, not the frontend login page. Use `API_DOMAIN` only if its reverse proxy routes `/github/webhook` to that service; do not assume `WEB_DOMAIN` or any 200/307 response proves correct delivery.

Keep **Redirect on update** enabled. After installing or changing repository access, finish the **Setup URL** browser round trip back to Kodus. A successful `ping` or an ignored `installation` event does not create the Kodus integration.

In Kodus Git Settings, confirm that the expected repository is connected. Then open a test pull request and check both the GitHub delivery response and Kodus webhook/worker logs. If connection is missing, check installation repository access, approved permissions, the Setup URL, and proxy routing.

[GitHub registration reference](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).