> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braingrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your project to GitHub

> Complete guide to permissions and installation of the BrainGrid GitHub App

Installing the BrainGrid GitHub App requires specific permissions on your GitHub repository. This guide explains who can install the app and how to get the necessary permissions.

## Permission Requirements

<Warning>
  You must have **Admin** or **Owner** permissions to install the BrainGrid GitHub App on a repository.
</Warning>

### Who Can Install GitHub Apps?

<table>
  <thead>
    <tr>
      <th>Role</th>
      <th>Can Install?</th>
      <th>Limitations</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Organization Owner**</td>
      <td>✅ Yes</td>
      <td>Can install on any repository in the organization</td>
    </tr>

    <tr>
      <td>**Repository Admin**</td>
      <td>✅ Yes\*</td>
      <td>Only on repos where they have admin rights, and only if the app doesn't request org-level permissions</td>
    </tr>

    <tr>
      <td>**Personal Repo Owner**</td>
      <td>✅ Yes</td>
      <td>Full control over their personal repositories</td>
    </tr>

    <tr>
      <td>**Maintainer/Write/Triage/Read**</td>
      <td>❌ No</td>
      <td>Can request installation, but owner must approve</td>
    </tr>
  </tbody>
</table>

<Note>
  **Important**: Organization owners can restrict repository admins from installing GitHub Apps in their organization settings.
</Note>

## Installation Steps

<Steps>
  <Step title="Check Your Permissions">
    Before starting, verify you have the necessary permissions:

    1. Go to your repository on GitHub
    2. Click **Settings** (if you don't see it, you don't have admin access)
    3. Look for **Collaborators & teams** in the sidebar

    If you can't access Settings, you'll need to request admin access first.
  </Step>

  <Step title="Start the Installation">
    Go to the [Integrations](https://app.braingrid.ai/agent/integrations) section in the BrainGrid console.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/braingrid/images/github-installation-001.png" alt="Integrations" />
    </Frame>

    Or click **Connect GitHub** from your BrainGrid dashboard.
  </Step>

  <Step title="Select Installation Location">
    Choose where to install:

    * **Personal account**: Select your username
    * **Organization**: Select the organization (you must be an owner or admin)

    <Info>
      If you're not an owner/admin, you'll see "Request" instead of "Install"
    </Info>
  </Step>

  <Step title="Choose Repository Access">
    Select which repositories BrainGrid can access:

    <CardGroup cols={2}>
      <Card title="All repositories" icon="globe">
        Grants access to all current and future repos
      </Card>

      <Card title="Only select repositories" icon="list">
        Choose specific repositories from a list
      </Card>
    </CardGroup>

    <Warning>
      We recommend selecting only the repositories you plan to use with BrainGrid
    </Warning>
  </Step>

  <Step title="Review Permissions">
    Carefully review the permissions BrainGrid is requesting:

    * **Read** access to code and metadata
    * **Write** access to issues and pull requests
    * **Read** access to actions and workflows

    These permissions allow BrainGrid to analyze your code and validate PRs.
  </Step>

  <Step title="Complete Installation">
    Click the installation button:

    * **Install** - If you have full permissions
    * **Install & Request** - If you have partial permissions
    * **Request** - If you need owner approval

    <Note>
      If you see "Request", the organization owner will receive a notification to approve your request
    </Note>
  </Step>
</Steps>

## Getting Admin Access

If you don't have the necessary permissions, here's how to get them:

### For Organization Repositories

If you're an admin and need to grant access to someone:

<Steps>
  <Step title="Navigate to Repository Settings">
    1. Go to the repository on GitHub
    2. Click **Settings** → **Collaborators & teams**
  </Step>

  <Step title="Add the User">
    1. Click **Add people** or **Add teams**
    2. Search for the user by their GitHub username
    3. Select them from the dropdown
  </Step>

  <Step title="Set Admin Role">
    1. In the role dropdown, select **Admin**
    2. Click **Add \[username] to \[repository]**
  </Step>
</Steps>

The user now has admin access and can install GitHub Apps.

### For Personal Repositories

<Warning>
  Personal repositories only have two roles: **Owner** (you) and **Collaborators** (write access only).

  Collaborators cannot have admin rights on personal repositories.
</Warning>

If you need multiple admins, consider:

1. **Transfer to an Organization**: Move your repository to an organization where you can assign admin roles
2. **Create an Organization**: Set up a new organization for your projects

## Troubleshooting

<AccordionGroup>
  <Accordion title="I don't see the Settings tab">
    You don't have admin access to the repository. Contact the repository admin or owner.
  </Accordion>

  <Accordion title="I clicked Install but nothing happened">
    Check if:

    * You selected at least one repository
    * Your organization has restrictions on GitHub App installations
    * You have a pending request waiting for approval
  </Accordion>

  <Accordion title="The installation was rejected">
    The organization owner may have concerns about:

    * The permissions requested
    * Organization policies
    * Security requirements

    Discuss with them and share BrainGrid's security documentation.
  </Accordion>

  <Accordion title="Can't find the Collaborators & teams option">
    * For personal repos: Look for **Manage access** instead
    * For org repos: You might not have admin permissions
    * Some organizations hide this based on policies
  </Accordion>
</AccordionGroup>

## Quick Reference

### Installation URL

```
https://github.com/apps/braingrid/installations/new
```

### Required Permissions

* **Minimum**: Repository Admin (with restrictions)
* **Recommended**: Organization Owner (full control)

### Can't Install?

1. Check your repository role
2. Request admin access if needed
3. Or ask an admin to install for you

## Next Steps

Once you've successfully installed the BrainGrid GitHub App:

<CardGroup cols={2}>
  <Card title="Continue with Quickstart" icon="rocket" href="/quickstart">
    Return to the quickstart guide to analyze your repository
  </Card>

  <Card title="Learn More" icon="book" href="/what-is-braingrid">
    Understand how BrainGrid works with your code
  </Card>
</CardGroup>

## Additional Resources

* [GitHub's official guide on managing repository access](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository)
* [Understanding GitHub App permissions](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)
* [Organization roles in GitHub](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization)