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

# Connect GitHub repositories

> Give Loop access to your source code to investigate trace failures, understand application behavior, and suggest fixes.

export const feature_0 = "The GitHub integration"

export const verb_0 = "is"

Connect GitHub repositories so Loop can move from a failing trace to the code that explains it, with source code and production evidence in the same investigation. Ask Loop to:

* Find the tool implementation or prompt logic behind an unexpected response.
* Compare failing and successful traces with the code to identify a likely cause.
* Suggest a targeted fix and a regression test based on the failure.

The integration provides read-only GitHub access: Loop can clone and fetch repositories, but cannot push changes or open pull requests.

<Warning>
  {feature_0} {verb_0} in [private preview](/docs/feature-lifecycle), available to a limited set of customers. To request access, [contact Braintrust](https://braintrust.dev/contact).
</Warning>

## Connect GitHub

You need the **Manage settings** organization permission to connect GitHub and set the organization's default connection. [Organization owners](/docs/admin/access-control#built-in-permission-groups) have this permission by default. You also need to own the GitHub account or be an administrator of the GitHub organization you're connecting.

<Steps>
  <Step title="Connect an installation">
    Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="toy-brick" /> Integrations**](https://www.braintrust.dev/app/~/configuration/org/integrations) and click <Icon icon="plus" /> **Connect GitHub**.

    Authorize access in GitHub, then choose an existing installation and click **Connect**, or click **Install in a new organization**. When installing the [Braintrust GitHub App](https://github.com/apps/braintrustdata), select the repositories you want it to access.

    Back in Braintrust, click **Show repositories** to check the installation's repository access.
  </Step>

  <Step title="Set the organization default">
    In organization **Integrations** settings, click **Set as default** on the installation you want Loop to use. Projects without an explicit connection inherit this default. Existing explicit project connections take precedence over the organization default.
  </Step>

  <Step title="Use the code in Loop">
    Start a new [Loop thread](/docs/loop) in the project and ask a question that combines traces with source code:

    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Investigate the most common tool-call failure in this project's traces from the past week. Find the relevant code in the connected repository, explain the likely cause, and suggest a fix and a regression test. Include example traces and file paths.
    ```

    Loop automatically clones up to five authorized repositories when it creates the sandbox. Each checkout starts with the latest commit on the default branch, under `github/<owner>/<repo>` in the sandbox working directory. Ask Loop to clone another authorized repository when you need it.
  </Step>
</Steps>

## Repository access and security

GitHub read access uses a short-lived token covering every repository available to the connected GitHub App installation. For Git operations, the egress proxy supplies that token only for repositories selected for Loop and only for cloning or fetching. The proxy does not authorize Git pushes. GitHub tokens are not passed to the model or stored in the sandbox. The sandbox receives ephemeral proxy credentials, while repository source files remain in the sandbox for Loop to inspect.

<Warning>
  Connecting a repository makes its code available through Loop to people with read access to the Braintrust project. Access uses the [Braintrust GitHub App](https://github.com/apps/braintrustdata) installation, not each person's GitHub account. Choose repositories and project membership accordingly.
</Warning>

## Manage connections

<AccordionGroup>
  <Accordion title="Change or remove the organization default">
    In organization **Integrations** settings, click **Set as default** on another installation to change the default, or **Remove default** to stop providing a default connection.

    These changes affect projects that inherit the organization default. Existing explicit project connections remain unchanged.

    <Warning>
      Changing or removing the default does not erase repository files already cloned into an existing sandbox. See [sandbox lifecycle](/docs/loop/manage#sandboxes) for how sandbox files are retained.
    </Warning>
  </Accordion>

  <Accordion title="Change repository access or disconnect GitHub">
    Change the repositories available to the Braintrust GitHub App in GitHub's installation settings. In Braintrust's organization **Integrations** settings, use **Show repositories** to check access or <Icon icon="trash-2" /> **Disconnect** to remove the connection.

    <Warning>
      Disconnecting an installation removes access through it for every Braintrust project that uses it. Projects explicitly connected to that installation do not fall back to the organization default. Disconnecting does not delete existing sandbox checkouts.
    </Warning>
  </Accordion>

  <Accordion title="Troubleshoot a missing repository">
    Check that the installation is active, the repository appears under **Show repositories**, and the installation is marked as the organization default. An existing explicit project connection takes precedence over that default. If the repository is authorized but was not automatically cloned, ask Loop to clone it by its `owner/repo` name.

    Start a new thread after changing the connection so Loop creates a new sandbox and prepares the checkouts. A failed checkout does not prevent the rest of Loop from working. Ask Loop to check whether the repository is available before continuing a source-code task.
  </Accordion>
</AccordionGroup>

## Limitations

* **Braintrust-hosted deployments only.** This integration is not yet available on self-hosted deployments.
* **Read-only GitHub access.** Loop can clone and fetch repositories, inspect code, and suggest fixes. It cannot push changes or open pull requests through this integration. Apply and submit suggested changes through your own development workflow.
* **Up to five automatic checkouts.** Loop automatically clones the first five authorized repositories, ordered by GitHub repository ID. However, you can ask Loop to clone additional authorized repositories.
* **Shallow checkouts.** Each checkout starts with the latest default-branch commit, without tags or earlier history. Ask Loop to fetch additional history or updates when needed.

## Next steps

* [What Loop can do](/docs/loop/capabilities) for more investigation workflows.
* [Connect external MCP servers](/docs/loop/mcp) to add context from issue trackers and other services.