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

> Install the Garth GitHub App on your organization or personal account for AI-powered automated code reviews and pull request feedback.

Garth connects to GitHub in two ways: the **Garth GitHub App** (this page) or a **personal access token**. Use the App when you want GitHub to manage permissions and you prefer not to rotate a token. For GitHub Enterprise Server, or when app installation is blocked by organization policy, use [GitHub via PAT](/setup/github-pat) instead.

<Warning>
  Only one GitHub connection can be active at a time. To switch methods, remove
  the existing connection first — uninstall the Garth App, or disconnect the
  token — then wait a few minutes and reload the integrations page.
</Warning>

<Warning>
  You must have **owner-level access** for the GitHub organization or repository
  you intend to connect. Without these administrative privileges you cannot
  install the Garth GitHub App.
</Warning>

## Connect your GitHub account

<Steps>
  <Step title="Access the Garth portal">
    Open your browser and navigate to the [Garth dashboard](https://app.heygarth.ai/).
  </Step>

  <Step title="Sign in">
    Select **Continue with Google** or **Continue with Microsoft** to authenticate via OAuth.

    <Tip>
      If you don't have a Google or Microsoft account, sign up using username and password on [app.heygarth.ai](https://app.heygarth.ai/).
    </Tip>
  </Step>

  <Step title="Create a Garth API key">
    In the left navigation, go to [**Developer → API Keys**](https://app.heygarth.ai/developer/api-keys) and click **Create API Key**.

    <Warning>
      Copy the API key and store it securely. It is shown only once.
    </Warning>
  </Step>

  <Step title="Install the Garth GitHub App">
    In Garth, go to [**Settings → Integrations**](https://app.heygarth.ai/settings/integrations), select the **GitHub** tab, choose **GitHub App**, and click **Open Link** — or navigate directly to the [Garth GitHub App](https://github.com/apps/garthpragent) and click **Install**. Sign in to GitHub if prompted.

    <Frame caption="The Garth dashboard lists the installation steps and links out to GitHub">
      <img src="https://mintcdn.com/na-f445b234/fN_JQ_Q5_GrbY_HS/images/setup/github_app_install.png?fit=max&auto=format&n=fN_JQ_Q5_GrbY_HS&q=85&s=9e7b99d1e261d6af191d52acefd0f35f" alt="Garth GitHub App installation steps shown in the Garth dashboard" width="1609" height="476" data-path="images/setup/github_app_install.png" />
    </Frame>
  </Step>

  <Step title="Choose your workspace">
    Select the GitHub organization or personal account where Garth should be installed.

    <Tip>
      If your organization does not appear, verify you have the correct administrative rights and check your GitHub App installation settings.
    </Tip>
  </Step>

  <Step title="Configure repository scope">
    Choose which repositories Garth can access:

    * **All repositories** — installs Garth on every current and future repository.
    * **Select repositories** — restricts Garth to specific projects you choose manually.

    <Info>
      Garth requires read/write access to pull requests and checks to post code reviews. **Your source code is never stored on Garth's servers.**
    </Info>

    Click **Install** to apply.
  </Step>

  <Step title="Activate with your API key">
    After clicking **Install**, you are redirected to the Garth platform. Enter
    the API key you created earlier to complete the activation.
  </Step>

  <Step title="Start reviewing">
    Setup is complete. Open or update a pull request in any tracked repository to see Garth's automated AI reviews in action.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="App installation issues">
    If you cannot install the Garth GitHub App:

    1. **Verify owner-level access** — confirm you have **Owner** permissions for the organization or repository.
    2. **Check organization settings** — some organizations restrict third-party app installations; an organization owner may need to approve Garth before installation succeeds.
    3. **Re-trigger the installation** — return to the [Garth GitHub App](https://github.com/apps/garthpragent) page and attempt the installation again.
    4. **Contact your GitHub admin** — if organization policies block app installations, your GitHub organization administrator must grant approval.
  </Accordion>

  <Accordion title="Reviews not appearing">
    If Garth is installed but not reviewing pull requests:

    1. **Confirm repository scope** — verify the repository is included under **All repositories** or is explicitly listed under **Select repositories** in your App installation settings.
    2. **Check API key activation** — ensure you completed the API key activation step after installing the GitHub App.
    3. **Verify pull request events** — Garth triggers on newly opened or updated pull requests. Re-open the PR or push a new commit to trigger a review.
  </Accordion>

  <Accordion title="Add or remove repositories">
    To change which repositories Garth can access after installation:

    1. **Open organization settings** — in GitHub, go to your organization's **Settings**.
    2. **Navigate to GitHub Apps** — under **Third-party Access**, select **GitHub Apps**.
    3. **Locate GarthPRAgent** — find the installed **GarthPRAgent** app and click **Configure**.
    4. **Update repository access** — in the **Repository access** section, add or remove repositories as needed, then **Save**.
  </Accordion>

  <Accordion title="Switch to a personal access token">
    Only one GitHub connection can be active at a time. To move from the App to a token:

    1. **Uninstall the Garth GitHub App** — in GitHub, open your organization's **Settings → Third-party Access → GitHub Apps**, find **GarthPRAgent**, and uninstall it.
    2. **Wait a few minutes** and reload [Settings → Integrations](https://app.heygarth.ai/settings/integrations) in Garth.
    3. **Connect the token** — follow [GitHub via PAT](/setup/github-pat).
  </Accordion>

  <Accordion title="Authentication errors">
    If you receive authentication or permission errors:

    1. **Re-authenticate** — log out and back into the [Garth dashboard](https://app.heygarth.ai/) and retry connecting your GitHub account.
    2. **Regenerate your API key** — go to **Developer → API Keys** in Garth, revoke the old key, and create a new one.
    3. **Reinstall the GitHub App** — uninstall and reinstall the Garth GitHub App from your GitHub organization settings.
    4. **Check SSO enforcement** — if your organization uses SAML SSO, you may need to authorize the Garth GitHub App for SSO access from your GitHub personal settings.
  </Accordion>
</AccordionGroup>