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

# GitHub

> Create and configure the on-prem Garth PR Review Agent (GPRA) GitHub App for your self-hosted deployment.

<Info>
  This page covers **on-prem (self-hosted)** setup. You create your own GitHub App
  so webhook events and API traffic stay inside your infrastructure. For the
  hosted SaaS integration, see [Setup → GitHub](/setup/github).
</Info>

<Warning>
  You must have **owner-level access** to the GitHub organization to create an
  organization-owned GitHub App and generate its credentials.
</Warning>

## Create the GPRA GitHub App

<Steps>
  <Step title="Open organization settings">
    Navigate to your organization's app settings:

    ```
    https://github.com/organizations/<org>/settings/apps
    ```

    Replace `<org>` with your GitHub organization slug.
  </Step>

  <Step title="Open GitHub Apps">
    Under **Developer settings**, select **GitHub Apps**.
  </Step>

  <Step title="Create a new app">
    Click **New GitHub App** and fill in the details below.

    | Field               | Value                                                       |
    | ------------------- | ----------------------------------------------------------- |
    | **GitHub App name** | `garth-<org>`                                               |
    | **Homepage URL**    | `Garth: The AI Productivity Platform For Engineering Teams` |
    | **Callback URL**    | `https://<dns-host>/api/garth-assist/oauth/github/callback` |
    | **Setup URL**       | `https://<dns-host>/api/github/validation`                  |
    | **Webhook URL**     | `https://<dns-host>/api/webhook/github`                     |
    | **Secret**          | A strong, randomly generated secret                         |

    <Tip>
      Replace `<dns-host>` with the DNS host of your on-prem Garth deployment.
      Generate the webhook secret with a secure random generator (for example
      `openssl rand -hex 32`) and store it in the `GITHUB_WEBHOOK_SECRET`
      environment variable.
    </Tip>
  </Step>

  <Step title="Set permissions">
    Under **Repository permissions**, grant:

    | Permission          | Access         |
    | ------------------- | -------------- |
    | **Actions**         | Read-only      |
    | **Checks**          | Read-only      |
    | **Commit statuses** | Read-only      |
    | **Contents**        | Read-only      |
    | **Deployments**     | Read-only      |
    | **Issues**          | Read and write |
    | **Metadata**        | Read-only      |
    | **Pull requests**   | Read and write |

    Under **Organization permissions**, grant:

    | Permission  | Access    |
    | ----------- | --------- |
    | **Members** | Read-only |

    Under **Account permissions**, grant:

    | Permission          | Access    |
    | ------------------- | --------- |
    | **Email addresses** | Read-only |
  </Step>

  <Step title="Subscribe to events">
    Under **Subscribe to events**, enable:

    * Create (branch or tag created)
    * Check run (check run is created, requested, rerequested, or completed)
    * Deployment status (deployment status updated from the API)
    * Issues
    * Member
    * Organization
    * Issue comment
    * Label
    * Pull request
    * Pull request review
    * Pull request review thread
    * Push
    * Status
    * Workflow job
    * Workflow run
  </Step>

  <Step title="Create the app">
    Click **Create GitHub App** to finish creating the app.
  </Step>

  <Step title="Generate a private key">
    On the app's settings page, scroll to **Private keys** and click
    **Generate a private key**. GitHub downloads a `.pem` file — store it securely.

    <Warning>
      The private key is shown/downloaded only once. Keep the `.pem` file safe; it
      grants full access to the app.
    </Warning>

    <Note>
      The `.pem` file content spans multiple lines, but `GITHUB_PRIVATE_KEY` must be
      a single line. Replace every newline in the key with the literal characters
      `\n` before setting the environment variable.

      On Linux/macOS:

      ```bash theme={null}
      awk 'NF {sub(/\r/, ""); printf "%s\\n", $0}' private-key.pem
      ```

      On Windows (PowerShell):

      ```powershell theme={null}
      ((Get-Content private-key.pem -Raw) -replace "`r`n", "`n").TrimEnd("`n") -replace "`n", "\n"
      ```
    </Note>
  </Step>

  <Step title="Generate a client secret">
    On the app's **General** settings page, note the **Client ID**, then under
    **Client secrets** click **Generate a new client secret** and copy the value.

    <Warning>
      The client secret is shown only once. Copy and store it securely before
      leaving the page.
    </Warning>
  </Step>
</Steps>

## Environment variables

After the app is created, record the following values for your on-prem deployment:

| Environment variable    | Value                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| `GITHUB_APP_ID`         | The **App ID** shown on the app's settings page                                                   |
| `GITHUB_PRIVATE_KEY`    | The **private key** (`.pem`) generated in step 8, on a single line with newlines replaced by `\n` |
| `GITHUB_WEBHOOK_SECRET` | The **webhook secret** you set in step 3                                                          |
| `GITHUB_CLIENT_ID`      | The **Client ID** shown on the app's General settings page                                        |
| `GITHUB_CLIENT_SECRET`  | The **client secret** generated in step 9                                                         |