> ## Documentation Index
> Fetch the complete documentation index at: https://personal-ce79cb71.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and Connect the BugViper GitHub App

> Step-by-step guide to installing the BugViper GitHub App on your GitHub organization or personal account and linking it to your dashboard.

BugViper runs as a GitHub App, which means it receives webhook events directly from GitHub and uses its own identity to clone repositories and post comments. Installation takes two minutes: you authorize the app on GitHub, then sign in to the BugViper dashboard to link your installation. No code changes, no CI edits, and no tokens to manage manually.

<Steps>
  <Step title="Go to the GitHub Marketplace or your BugViper dashboard">
    Navigate to the [GitHub Marketplace](https://github.com/marketplace) and search for **BugViper**, or open the BugViper dashboard and click **Install GitHub App**. Both paths take you to the same GitHub installation page.
  </Step>

  <Step title="Click Install and choose your account">
    On the GitHub App installation page, click **Install**. Select either your personal account or a specific GitHub organization where you want BugViper to run.
  </Step>

  <Step title="Select which repositories BugViper can access">
    Choose the scope of access:

    * **All repositories** — BugViper will be available on every current and future repository in your account or organization.
    * **Only select repositories** — Pick specific repositories from the list. You can expand access later from your GitHub App settings.
  </Step>

  <Step title="Authorize the required permissions">
    Review and accept the permissions BugViper requests. GitHub will display these before you confirm the installation.

    | Permission      | Access Level | Why BugViper needs it                                         |
    | --------------- | ------------ | ------------------------------------------------------------- |
    | Contents        | Read         | Clone the repository at the PR head SHA into a secure sandbox |
    | Issues          | Read & Write | Create, update, and track issues linked to review findings    |
    | Pull requests   | Read & Write | Read PR diffs and post inline review comments and summaries   |
    | Metadata        | Read         | Access basic repository information for the dashboard         |
    | Commit comments | Read & Write | Post commit-level comments alongside PR reviews               |
    | GitHub Actions  | Read         | Read workflow context when analyzing CI-related changes       |

    Click **Install & Authorize** to confirm.
  </Step>

  <Step title="You'll be redirected to BugViper onboarding">
    After authorization, GitHub redirects you to the BugViper onboarding flow. Sign in with GitHub OAuth if you haven't already, then follow the prompts to link your GitHub App installation to your dashboard account. Once linked, BugViper is active and ready to review pull requests in your selected repositories.
  </Step>
</Steps>

<Note>
  If you install the GitHub App before signing in to BugViper, your installation is not lost. BugViper stores pending installations for up to **30 days**. Sign in to the dashboard at any point within that window and BugViper will automatically detect and link your installation during onboarding.
</Note>

## GitHub App permissions explained

BugViper requests only the permissions it needs to perform code review and issue tracking. No write access to your source code is ever requested.

| Permission      | Access Level | Why BugViper needs it                                                          |
| --------------- | ------------ | ------------------------------------------------------------------------------ |
| Contents        | Read         | Clone the repository at the PR head SHA into a secure E2B sandbox for analysis |
| Issues          | Read & Write | Create and update issues in your repository that are linked to review findings |
| Pull requests   | Read & Write | Read the PR diff and post inline comments and a structured review summary      |
| Metadata        | Read         | Access repository name, visibility, and owner information for the dashboard    |
| Commit comments | Read & Write | Post comments at the commit level alongside full PR review output              |
| GitHub Actions  | Read         | Read workflow run context to support analysis of CI-related file changes       |

<Warning>
  Removing the BugViper GitHub App from your account or organization immediately stops all reviews. Webhooks will no longer be delivered, and BugViper will not be able to clone repositories or post comments. Your existing review history and analytics in the dashboard are preserved, but no new reviews will run until you reinstall the app.
</Warning>