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

# Connect a repo

> Add a repository so agents can clone it, branch, and push their work back.

Agents work on **your** repositories. Connecting one creates a **project** and
(for private repos) stores an encrypted credential the workspace uses to clone.

## Connect one

<Frame caption="Connect a repository — the auth-method card shows exactly which scopes to grant.">
  <img src="https://mintcdn.com/agent-bees/HUTI08XX3esZvrRw/images/connect-repo.png?fit=max&auto=format&n=HUTI08XX3esZvrRw&q=85&s=9b6a71e1b37c7d93dbd90622e7d4f1ab" alt="Connect a repo screen" width="1440" height="900" data-path="images/connect-repo.png" />
</Frame>

From the Dashboard, choose **Connect repo**, then:

<Steps>
  <Step title="Repository URL">
    e.g. `https://github.com/org/repo`. Optionally set a **project name** (defaults to the URL).
  </Step>

  <Step title="Auth method">
    GitHub PAT, GitHub App installation, GitHub OAuth, GitLab PAT, or GitLab OAuth. A per-method
    card shows the exact scopes to grant and links to create the token.
  </Step>

  <Step title="Token (or installation ID)">
    Paste your token — **or leave it blank for a public repo** (it's cloned anonymously). For a
    GitHub App, enter the **installation ID** instead.
  </Step>

  <Step title="(Optional) Probe">Check the URL is reachable and see the default branch.</Step>

  <Step title="Connect">
    Creates the project and, if you provided a credential, an encrypted repo connection — then drops
    you on the project page.
  </Step>
</Steps>

## Scopes to grant

| Method             | Scopes                                              |
| ------------------ | --------------------------------------------------- |
| GitHub PAT         | `repo` (full); `read:org` if the org is private     |
| GitHub App         | Contents: R/W · Pull requests: R/W · Metadata: Read |
| GitHub OAuth       | `repo`, `read:user`, `user:email`                   |
| GitLab PAT / OAuth | `api`, `read_repository`, `write_repository`        |

## Public vs private

<Note>
  **Public repos need no token** — the workspace clones them anonymously. Only private repos require
  a credential. Leave the token field blank for public repos.
</Note>

## How credentials are stored

Your token is **envelope-encrypted** (AES-256-GCM under an org-scoped, KMS-wrapped
key) and stored only in the repo-connections table — the one place git credentials
live. Connections can be listed and **revoked** at any time; the git credential is
short-lived and revocable, and is never written into a task manifest.

<Tip>
  When an agent runs, it branches from your project's **default base branch**, works in its own
  `task/…` branch, and pushes back for review — it never commits directly to your default branch.
</Tip>