Home Getting Started GitHub App Installation & Troubleshooting Guide - Optibot / Optimal Insights

GitHub App Installation & Troubleshooting Guide - Optibot / Optimal Insights

Last updated on Oct 29, 2025

Overview

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.

When you authorize a GitHub App, you’re granting it permission to act on behalf of your GitHub user (e.g. to write comments).

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

Who Can Install the App

  • Organization Owner

    Can install Optibot across the entire org and grant repo access.

  • Repo Admin

    Can install Optibot only on repos you administer (if no org-level permissions required).

  • Org Member (no admin rights)

    Can request installation — GitHub will email the org owner for approval.

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

How to Verify Installation

A. Organization Level

  1. Go to GitHub → Organization Settings → Third-party Access → GitHub Apps

  2. Confirm Agent Optibot and Optimal Insights appears in the list.

  3. Click Configure to view:

    • Permissions granted

    • Repositories connected

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

If GitHub didn’t send (or you can’t find) 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.
    👉 GitHub Official Guide – Installing a GitHub App from a third party

    👉 Optimal Insights Signup

    👉 Optibot (Code Review) Signup 

  5. Still blocked? Have your org owner follow the same link to approve directly

Common Issues

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

If any of these are missing, share this doc and resolve before the call.

Quick Reference Links