# GitHub App Installation & Troubleshooting Guide

Before Optibot can review pull requests or measure engineering productivity, it needs permission to connect to your organization’s repositories via the Optibot & Optimal Insights GitHub App.

This guide explains:

- How to install the Optibot and Optimal Insights GitHub App
- How to confirm they’re installed correctly
- How to re-request the installation email if it’s missing
- How to troubleshoot common setup issues

You can install Optibot and Insights on multiple accounts (personal and organization). Each installation controls which repositories the app can access.

## Installation Flow

### 1. Open the installation link

**Optibot (Code Reviewer):**

```
https://github.com/apps/agent-optibot/installations/new
```

**Optimal Insights:**

```
https://github.com/apps/optimal-insights/installations/new
```

### 2. Choose where to install

Select your organization or your personal account.

### 3. Select repository access

- **All repositories** (recommended)
- or **Only selected repositories** (manually choose repos)

### 4. Review requested permissions

Confirm you’re comfortable granting access to read/write PRs, commits, and metadata.

### 5. Click Install or Request

- **Install** → you have permission to complete it.
- **Request** → only org owners can approve. GitHub will email them automatically.

> **Note:** Installation ≠ Authorization. Both may be required depending on org settings.

## Who Can Install the App

| Role | Capability |
| --- | --- |
| **Organization Owner** | Can install Optibot across the entire org and grant repo access |
| **Repo Admin** | Can install Optibot only on repos you administer |
| **Org Member (no admin)** | Can request installation — GitHub will email the org owner for approval |

If you see a **“Request”** button instead of **“Install”**, the organization owner must approve.

## How to Verify Installation

### A. Organization Level

1. Go to [GitHub](https://github.com/) → Organization Settings → Third-party Access → GitHub Apps
2. Confirm **Agent Optibot** and **Optimal Insights** appear in the list.
3. Click **Configure** to view permissions granted, repositories connected, and option to suspend/remove.

### B. Repository Level

1. Go to Repo → Settings → Integrations → GitHub Apps
2. Confirm Optibot & Optimal Insights is listed.
3. Check if it has access to the correct repo(s).

## Didn’t Receive the Installation Email?

1. Check spam/junk folders
2. Confirm you have org owner privileges — only owners receive approval emails
3. Visit **Settings → Installed GitHub Apps** to check if Optibot already appears
4. If not, visit the install URL again and reinstall manually
5. Still blocked? Have your org owner follow the same link to approve directly

→ [GitHub Official Guide – Installing a GitHub App from a third party](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party#installing-a-github-app)

## Troubleshooting Checklist

Before activation calls, confirm all boxes are checked:

- [ ]  Org owner accepted the install invite
- [ ]  Optibot appears under “Installed GitHub Apps”
- [ ]  Correct repositories are selected
- [ ]  Permissions include read/write on PRs and metadata
- [ ]  App installed at org or repo level (not just personal)
- [ ]  Team knows who to contact if re-request needed

## Quick Reference Links

- [Installing a GitHub App (Official)](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party#installing-a-github-app)
- [Viewing Installed Apps](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/reviewing-github-apps-installed-in-your-organization)
- [Requesting App Installation from Org Owner](https://docs.github.com/en/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner)
- [Optimal Insights Signup](http://insights.getoptimal.ai/signup)
- [Optibot (Code Review) Signup](https://agents.getoptimal.ai/signup)