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

# GitHub Integration

> Connect GitHub repositories to Corbulo

# GitHub Integration

Corbulo connects to GitHub through a GitHub App. The app receives webhook events when pull requests are opened and code is pushed, and has read access to your repository contents for analysis.

***

## Installation

<Steps>
  <Step title="Open Source Control settings">
    Go to **Settings > Source Control** in your Corbulo project.
  </Step>

  <Step title="Connect GitHub">
    Click **Connect GitHub**. You will be redirected to GitHub to install the Corbulo GitHub App.
  </Step>

  <Step title="Choose access level">
    Select whether to grant access to **all repositories** or only **selected repositories** in your organization. You can change this later from your GitHub settings.
  </Step>

  <Step title="Authorize the installation">
    Confirm the installation on GitHub. You will be redirected back to Corbulo.
  </Step>
</Steps>

After installing the GitHub App, go to the **Repos** page in your project to add repositories. You can add repos from any GitHub organization where the Corbulo App is installed.

***

## Permissions Required

The Corbulo GitHub App requests the following permissions:

| Permission              | Access       | Purpose                                                                               |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------- |
| **Repository contents** | Read         | Analyze source code for health scoring, convention detection, and architecture review |
| **Pull requests**       | Read & Write | Read PR metadata and diffs, post analysis results as comments                         |
| **Metadata**            | Read         | Repository information (name, language, default branch)                               |
| **Webhooks**            | Read & Write | Receive events when PRs are opened, updated, or merged and when code is pushed        |

<Note>
  Corbulo requests only the permissions it needs. Repository contents are accessed read-only and are never modified. Write access to pull requests is used solely to post analysis results.
</Note>

***

## What Triggers Analysis

| Event                             | What Happens                                                                                                         |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **PR opened or updated**          | PR analysis runs automatically. Issues are detected, merge readiness is evaluated, and results are posted to the PR. |
| **PR merged to default branch**   | An incremental health assessment runs. Scores are recalculated based on the changes introduced by the merge.         |
| **Code pushed to default branch** | The code graph and detected conventions are updated to reflect the latest state of the codebase.                     |

***

## Repository Selection

After installing the GitHub App, you manage which repositories are tracked from inside Corbulo:

1. Go to the **Repos** page in your project.
2. Click **Add Repository**.
3. Select repositories from the list of available repos (filtered by your GitHub App installation).
4. Confirm your selection.

Corbulo begins onboarding each repository immediately -- cloning the code, building the code graph, running analyzers, detecting conventions, and computing your initial health score.

You can add repositories from multiple GitHub organizations, as long as the Corbulo App is installed on each one.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pull request is not being analyzed">
    Verify the following:

    * The repository is added to your Corbulo project (check the **Repos** page).
    * The Corbulo GitHub App is installed on the organization that owns the repository.
    * Webhooks are active. Go to your GitHub organization settings, find the Corbulo app installation, and confirm that webhooks are being delivered.

    If webhooks show as delivered but analysis is not running, check the PR detail page in Corbulo for status information.
  </Accordion>

  <Accordion title="Analysis appears stuck">
    Open the PR in Corbulo and check the analysis status. If analysis has been running for more than 10 minutes, there may be an issue with the analysis worker. For self-hosted deployments, check that the worker service is running and healthy.
  </Accordion>

  <Accordion title="Missing permissions error">
    If Corbulo reports insufficient permissions, reinstall the GitHub App:

    1. Go to your GitHub organization settings.
    2. Find the Corbulo app under **Installed GitHub Apps**.
    3. Click **Configure** and verify the permissions match those listed above.
    4. If permissions are missing, uninstall and reinstall the app from **Settings > Source Control** in Corbulo.
  </Accordion>

  <Accordion title="Repository not appearing in the add list">
    The repository list is filtered by your GitHub App installation. If a repository does not appear:

    * Confirm the app is installed on the correct organization.
    * Confirm the app has access to that specific repository (if you chose "selected repositories" during installation).
    * You can update repository access from your GitHub organization settings under **Installed GitHub Apps > Corbulo > Configure**.
  </Accordion>
</AccordionGroup>