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

# GitHub App

> Create a private GitHub App to connect your instance with your repositories.

Compiler reads your code through a private GitHub App that you own. This guide walks through creating one and connecting it to your self-hosted instance.

## Prerequisites

* A GitHub account with permission to create GitHub Apps (a personal account or an organization admin)
* The base URL of your instance (for example `https://compiler.yourdomain.com`)

## Step 1: Create a new GitHub App

1. Go to **GitHub Settings**:
   * For a personal account: `https://github.com/settings/apps/new`
   * For an organization: `https://github.com/organizations/YOUR_ORG/settings/apps/new`

2. Fill in the basic information:

   | Field | Value |
   | - | - |
   | **GitHub App name** | A unique name (for example `YourCompany Compiler`) |
   | **Homepage URL** | Your instance URL (for example `https://compiler.yourdomain.com`) |

3. Set both the **Callback URL** and, under **Post installation**, the **Setup URL** to:

   ```text theme={null}
   https://compiler.yourdomain.com/onboarding/github-callback
   ```

   GitHub sends people to the Setup URL after they install the app, so without it you won't be brought back to your instance. Also check **Redirect on update**, so changing the repository selection later brings you back too.

4. Uncheck **Expire user authorization tokens**. Compiler doesn't need it.

5. Uncheck **Request user authorization (OAuth) during installation**. Compiler doesn't need it.

6. Under **Webhook**, leave **Active** unchecked. Compiler doesn't use webhooks, so no webhook URL is needed.

## Step 2: Configure permissions

Under **Repository permissions**, set:

| Permission | Access level | Purpose |
| - | - | - |
| **Contents** | Read-only | Clone and read repository files |
| **Metadata** | Read-only | Access repository information |

Leave all other permissions as **No access**.

## Step 3: Choose where it can be installed

Under **Where can this GitHub App be installed?**, select **Only on this account** for private use.

## Step 4: Create the app

Click **Create GitHub App**. GitHub takes you to your new app's settings page.

## Step 5: Note your app credentials

After creation, collect these values.

<AccordionGroup>
  <Accordion title="App ID" icon="hashtag" defaultOpen>
    Found at the top of the app settings page:

    ```text theme={null}
    App ID: 123456
    ```
  </Accordion>

  <Accordion title="App slug" icon="link" defaultOpen>
    Found in the URL of your app's public page:

    ```text theme={null}
    https://github.com/apps/your-app-slug
                           ^^^^^^^^^^^^^^
    ```
  </Accordion>

  <Accordion title="Private key" icon="key" defaultOpen>
    1. Scroll down to the **Private keys** section
    2. Click **Generate a private key**
    3. A `.pem` file downloads automatically

    The private key looks like:

    ```text theme={null}
    -----BEGIN RSA PRIVATE KEY-----
    MIIEowIBAAKCAQEA...
    ...many lines of base64...
    -----END RSA PRIVATE KEY-----
    ```

    <Warning>
      Keep this file secure. It's used to authenticate your app.
    </Warning>
  </Accordion>
</AccordionGroup>

## Step 6: Configure your instance

1. Sign up as the first user on your instance. Setup asks for the GitHub App straight after sign-up. To change it later, open **Settings** > **GitHub** as an admin.

2. Enter your credentials:

   | Field | Value |
   | - | - |
   | **App ID** | The numeric App ID from step 5 |
   | **App Slug** | The slug from your app's URL |
   | **Private Key** | The entire contents of the `.pem` file |

3. Click **Continue**. Compiler checks the credentials before it moves on.

## Step 7: Install the app on your repositories

1. Click **Install GitHub App**
2. GitHub asks you to authorize the installation
3. Select which repositories to grant access to:
   * **All repositories**: access to all current and future repositories
   * **Only select repositories**: choose specific repositories (recommended)
4. Click **Install**
5. GitHub sends you back to your instance through the Setup URL from step 1

## Step 8: Finish setup

1. Choose your AI provider
2. Create your first project and pick the repositories it should cover from those the app can access
3. Compiler clones the repositories in the background. You can start asking questions while they sync

To add repositories later, open **Settings**, choose the project, and go to **Repositories**.

## Permissions summary

| Permission | Level | Required | Purpose |
| - | - | - | - |
| Contents | Read | Yes | Clone repos, read files |
| Metadata | Read | Yes | List repos, get info |
| All others | None | No | Not used |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.