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

# Connect GitHub

> Install the Onecortex GitHub app on your account or organization, choose which repositories it can read, and pick the folder that holds your agent.

Onecortex builds from a GitHub repository through the Onecortex GitHub app. You install it once per GitHub account or organization, and choose which repositories it can read.

## Connect

<Steps>
  <Step title="Start from Create agent">
    In the dashboard, open **Agents**, click **Create agent**, choose **GitHub repository**, and click **Connect GitHub**. You can also connect from **Settings**, under GitHub.
  </Step>

  <Step title="Install the app on GitHub">
    GitHub asks where to install the app: your personal account, or an organization you administer. Choose **All repositories**, or **Only select repositories** and pick them. Then install.
  </Step>

  <Step title="Pick the repository">
    Back in Onecortex, the wizard lists the repositories the app can read. Search, and pick one. Private repositories are marked **Private**.
  </Step>
</Steps>

A repository you granted later is not listed yet? Click **Refresh** under the list.

## What the app can do

The app asks for read only access, and nothing else:

| Permission | Access | Used for |
| - | - | - |
| Repository contents | Read only | Downloading the commit to build, and reading `agent.yml` |
| Repository metadata | Read only | Listing your repositories and branches |
| Email addresses | Read only | Your verified email address, when you sign in with GitHub |

Onecortex never writes to your repository: no commits, no branches, no pull requests, no status checks. Your source is never modified, and the build adds its own files beside it, in the build only.

## Monorepos and agent folders

An agent can live in any folder of a repository. After you pick the repository and branch, **Agent folder** lists every folder on that branch that holds an `agent.yml`. Choose one, or leave it empty for an agent at the repository root.

Only that folder is built: paths in `agent.yml` are relative to it and may not leave it. Several agents can deploy from folders of one repository, and a push rebuilds only the agents whose folder it touched. See [Automatic deploys](/deploy/auto-deploy).

## Manage connections

**Settings**, under GitHub, lists each connected account or organization with its number of repositories. To change which repositories the app can read, change the app's installation on GitHub, then **Refresh** in the wizard.

**Disconnect** removes a connection. It is refused while agents still deploy from it, with `<n> agents still deploy from this connection. Delete those agents first, or they will stop building.`