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

> Connect Garth to GitHub.com or GitHub Enterprise Server with a classic personal access token for automated code reviews.

Garth connects to GitHub in two ways: the **Garth GitHub App** or a **classic personal access token** (this page). Use a token when you run GitHub Enterprise Server, or when organization policy prevents installing a GitHub App. If neither applies, [GitHub via App](/setup/github-app) needs no token rotation.

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

<Info>
  The token owner must be an admin of the organization, or of every repository
  you want reviewed. The scopes below only grant what that account is already
  allowed to do. Token expiry is managed by you — Garth stops reviewing when the
  token lapses.
</Info>

## Step 1: Create a classic personal access token

<Warning>
  Do not use a personal user account. Code reviews are attributed to the token
  owner. Create a dedicated service account named `GPRABot` for this integration
  and grant it admin access to the organization or target repositories.
</Warning>

<Steps>
  <Step title="Authenticate as the service account">
    Log into GitHub using the dedicated Garth service account.
  </Step>

  <Step title="Open token settings">
    Go to **Settings → Developer settings → Personal access tokens (classic)** and click **Generate new token (classic)**.

    <Note>
      Garth requires a **classic** token. Fine-grained personal access tokens are not supported.
    </Note>
  </Step>

  <Step title="Name the token and set expiry">
    Give the token a clear name such as `Garth PR Token` and choose an expiry. Record the expiry date — when the token lapses, Garth stops reviewing until you replace it in the dashboard.
  </Step>

  <Step title="Select token scopes">
    Enable the following scopes:

    | Scope             | Purpose                                          |
    | ----------------- | ------------------------------------------------ |
    | `repo`            | Clone repositories and use the pull request APIs |
    | `read:org`        | Read organization and team details               |
    | `user:email`      | Read the account email address                   |
    | `admin:repo_hook` | Create and update repository webhooks            |
  </Step>

  <Step title="Save the token">
    Click **Generate token** and copy it immediately — **GitHub displays it only once.**
  </Step>
</Steps>

## Step 2: Link to Garth

<Steps>
  <Step title="Open Garth integrations">
    Log into the [Garth dashboard](https://app.heygarth.ai/) and navigate to [Settings → Integrations](https://app.heygarth.ai/settings/integrations).
  </Step>

  <Step title="Choose the token method">
    Select the **GitHub** tab, then choose **Personal Access Token**.

    <Frame caption="Choose how to connect GitHub: the Garth GitHub App or a Personal Access Token">
      <img src="https://mintcdn.com/na-f445b234/fN_JQ_Q5_GrbY_HS/images/setup/github_connection_options.png?fit=max&auto=format&n=fN_JQ_Q5_GrbY_HS&q=85&s=390010002911f264d3586f5a5ca87352" alt="Garth GitHub integration settings showing the GitHub App and Personal Access Token connection options" width="1612" height="451" data-path="images/setup/github_connection_options.png" />
    </Frame>
  </Step>

  <Step title="Enter your credentials">
    Provide the **Organization or User URL** and the **Personal Access Token** you just created, then click **Validate**.

    * Organization: `https://github.com/orgs/your-org`
    * Personal account: `https://github.com/your-username`
    * GitHub Enterprise Server: use your server host, for example `https://github.example.com/orgs/your-org`

    <Info>
      The token is encrypted at rest on Garth's servers. **Your source code is never stored on Garth's servers.**
    </Info>

    <Frame caption="Enter your Organization or User URL and Personal Access Token, then click Validate">
      <img src="https://mintcdn.com/na-f445b234/fN_JQ_Q5_GrbY_HS/images/setup/github_PAT_integration.png?fit=max&auto=format&n=fN_JQ_Q5_GrbY_HS&q=85&s=30ea0923b47a34474881da75a524ace3" alt="Garth GitHub integration form with Organization or User URL and Personal Access Token fields and the required token scopes" width="1613" height="755" data-path="images/setup/github_PAT_integration.png" />
    </Frame>
  </Step>

  <Step title="Confirm and save">
    Garth validates the token, shows the account it resolved, then saves the credentials and fetches your repositories.
  </Step>

  <Step title="Install repositories">
    Select the repositories you want Garth to review and click **Install Repositories**.

    <Info>
      **Automatic webhooks:** Garth installs webhooks on selected repositories automatically. No manual webhook configuration is required. Webhooks are also removed automatically when you uninstall a repository.
    </Info>
  </Step>
</Steps>

## Step 3: Activate and configure the repository

After installation, activate each repository under [Agent Setup → PR Review → Repository Setup](https://app.heygarth.ai/agents/pr-review/repository-setup).

Once a repository is activated, you can configure the following options:

1. **Files to Exclude** — specify file patterns that Garth should skip during reviews.
2. **Source Branches to Exclude** — exclude PRs originating from certain branches.
3. **Destination Branches to Exclude** — exclude PRs targeting certain branches.
4. **Auto Review** — enable or disable automatic reviews for new PRs on this repository.
5. **Repository PR Review Guidelines** — define custom review guidelines specific to this repository.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Validation fails">
    If **Validate** rejects your credentials:

    1. **Check the token type** — Garth requires a **classic** personal access token. Fine-grained tokens fail validation.
    2. **Check the scopes** — confirm `repo`, `read:org`, `user:email`, and `admin:repo_hook` are all selected. Scopes cannot be added to an existing classic token; regenerate it if one is missing.
    3. **Check the URL format** — use `https://github.com/orgs/your-org` for an organization or `https://github.com/your-username` for a personal account.
    4. **Check SSO enforcement** — if your organization uses SAML SSO, authorize the token for SSO from **Settings → Developer settings → Personal access tokens (classic)** in GitHub.
    5. **Confirm no existing connection is blocking** — only one GitHub connection can be active at a time. Uninstall the Garth GitHub App first if it is still installed.
  </Accordion>

  <Accordion title="Webhook issues">
    If Garth is not reviewing pull requests on an installed repository:

    1. **Check webhook status** — in the repository's **Settings → Webhooks**, verify the Garth webhook exists and recent deliveries succeeded.
    2. **Verify admin access** — the token owner needs admin access on the repository for `admin:repo_hook` to create webhooks.
    3. **Delete a stale webhook** manually, then untoggle and re-toggle the repository in the Garth dashboard to reinstall it.
  </Accordion>

  <Accordion title="Not receiving reviews">
    If Garth is installed but you are not receiving reviews:

    1. **Check repository activation** — go to [Agent Setup → PR Review → Repository Setup](https://app.heygarth.ai/agents/pr-review/repository-setup) and confirm the repository is activated.
    2. **Verify Auto Review is enabled** — ensure the **Auto Review** toggle is turned on for the repository.
    3. **Check branch exclusions** — confirm the source or destination branch of your PR is not listed under **Source Branches to Exclude** or **Destination Branches to Exclude**.
    4. **Check file exclusions** — verify that the files changed in your PR are not covered by patterns in **Files to Exclude**.
  </Accordion>

  <Accordion title="Token expired or rotated">
    Classic tokens expire on the date you set. When a token lapses or you rotate the service account:

    1. **Generate a replacement token** with the same scopes.
    2. **Update it in Garth** — go to **Settings → Integrations → GitHub** and re-enter the credentials, then click **Validate**.
    3. **Re-check repository tracking** — confirm your repositories are still installed and activated.
  </Accordion>

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

    1. **Disconnect the token** — in Garth, go to **Settings → Integrations → GitHub** and remove the existing connection.
    2. **Wait a few minutes** and reload the integrations page.
    3. **Install the App** — follow [GitHub via App](/setup/github-app).
  </Accordion>
</AccordionGroup>