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

# GitHub access

> Give agents authenticated git and gh for exactly the repositories and permissions you choose, with short-lived tokens and optional GitHub MCP tools.

A GitHub grant lets an agent clone, build, commit, push, and open pull requests with `git` and `gh` in its sandbox. It can also offer GitHub's MCP tools for API work. Each session receives its own short-lived token. The token can't do more than the GitHub App installation allows, the access level you grant, and the repositories you pick.

The TypeScript samples assume the `rl` client from [Client setup](/managed-agents/api#client-setup).

## Before you begin

* You need the organization developer or admin role to connect GitHub and to change an agent's access. See [Organizations and roles](/managed-agents/organizations-and-roles).
* You need a GitHub account that can install the GitHub App on the target organization or user account. Some organizations require an owner to approve new apps.
* If your environment restricts outbound network access, you need to be able to change its network policy. See [Allow GitHub hosts](#allow-github-hosts).

## What limits a session's access

Each layer can only narrow the one above it.

| Layer                   | Where you set it                                          | What it limits                                                                                   |
| ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| GitHub App installation | In GitHub, when you install the app                       | The accounts, repositories, and permissions the app holds. Nothing in Recursion can exceed this. |
| Agent grant             | The agent's **Integrations** section                      | The access level (`read`, `write`, or `full`) and, optionally, specific repositories.            |
| Session                 | The agent version the session runs, plus any vault grants | Which grants the session receives.                                                               |
| Tool surface            | The agent's **GitHub MCP tools** setting                  | Whether sessions use sandbox `git` and `gh`, GitHub MCP tools, or both.                          |

## Connect GitHub

1. In the sidebar, click **Integrations**, then click **Add integration**.
2. Choose **GitHub** and click **Continue**.
3. On GitHub, choose the organization or user account and the repositories the app can reach. Approve the installation.
4. Back on **Integrations**, confirm that the GitHub row shows **State** as **Active**.

Connecting grants nothing to any agent. You can connect several GitHub accounts, for example one per GitHub organization, and grant each separately. For the API flow and connection states, see [Integrations](/managed-agents/integrations).

## Grant GitHub to an agent

Choose the least access that completes the task.

| Access level | GitHub permissions in the token                                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`       | Read code, issues, pull requests, Actions, checks, and commit statuses. Can't push or comment. This is the default.                                            |
| `write`      | Everything in `read`, plus push commits, open and comment on issues and pull requests, rerun workflows, update checks and statuses, and change workflow files. |
| `full`       | Every permission the installation holds, including ones added to the app later. Use it only when a narrower level can't do the job.                            |

Pick repositories whenever you can. Without a repository list, the grant reaches every repository in the installation, including repositories added to it later.

<Tabs>
  <Tab title="Console">
    1. Open the agent. On **Configuration**, find **Integrations** and click **Add integration access**.
    2. Click **Select** next to the GitHub connection.
    3. Set **Access level** to **Read only**, **Read and write**, or **Full: everything the installation allows**.
    4. Clear **All authorized repositories** and pick the repositories, or keep it to cover the whole installation.
    5. Click **Use this access**, then click **Save new version**.
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":"css-variables"}
    await rl.managedAgents.createAgentVersion({
      agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
      body: {
        base_agent_version_id: 'c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21',
        name: 'Release engineer',
        model: 'anthropic/claude-sonnet-4-5',
        system: 'Fix failing tests and open a pull request with the change.',
        nativeIntegrations: [
          {
            connectionId: '31e6c9a4-2d75-48b0-a1f3-7c5e9d2b6a84',
            permission: 'write',
            resources: ['acme/api'],
          },
        ],
        disabled_integration_mcp_providers: ['github'],
      },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"theme":"css-variables"}
    curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \
      -H "Authorization: Bearer $RECURSION_API_KEY" \
      -H 'Content-Type: application/json' \
      -d '{
        "base_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
        "name": "Release engineer",
        "model": "anthropic/claude-sonnet-4-5",
        "system": "Fix failing tests and open a pull request with the change.",
        "nativeIntegrations": [{
          "connectionId": "31e6c9a4-2d75-48b0-a1f3-7c5e9d2b6a84",
          "permission": "write",
          "resources": ["acme/api"]
        }],
        "disabled_integration_mcp_providers": ["github"]
      }'
    ```
  </Tab>
</Tabs>

A new version replaces the whole definition, so send every field you want to keep. Name repositories as `owner/name`, up to 500. To find names, [list the connection's repositories](/managed-agents/integrations#list-github-repositories-and-pull-requests).

To give different sessions of the same agent different repositories or accounts, grant GitHub through a vault instead. See [Grant through a vault](/managed-agents/integrations#grant-through-a-vault).

## Allow GitHub hosts

A GitHub grant supplies a credential, not network access. If the environment's [network policy](/managed-agents/environments-reference) limits outbound traffic, allow these hosts, or `git` and `gh` can't reach GitHub:

| Host                            | Used for                                                     |
| ------------------------------- | ------------------------------------------------------------ |
| `github.com`                    | Git over HTTPS.                                              |
| `api.github.com`                | `gh` and other GitHub API calls.                             |
| `codeload.github.com`           | Repository archive downloads.                                |
| `objects.githubusercontent.com` | Git LFS transfers.                                           |
| `github-cloud.s3.amazonaws.com` | Git LFS transfers that GitHub redirects to its object store. |

`listIntegrationProviders` returns the same list as `egress_hosts` for `github`. GitHub MCP tools run outside the sandbox and don't need these rules.

## How the token reaches git and gh

* `git` receives the token through a credential helper when it talks to `github.com`. The helper refuses repositories outside the grant, even within the same installation.
* `gh` receives the token only for the command being run. It isn't stored in the sandbox's environment or written to disk.
* Tokens are short-lived and are fetched when a command needs one, so long sessions keep working.
* The model never receives the token in its context. A command the agent runs could still print it, so treat anything in the sandbox as visible to the agent.

When a session holds several GitHub connections, each serves its own account's repositories.

## Choose sandbox or MCP tools

| Surface                | Best for                                                                    | Where the token goes                                                       |
| ---------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Sandbox `git` and `gh` | Cloning, building, testing, committing, pushing, and opening pull requests. | To `git` and `gh` in the sandbox, as described above.                      |
| GitHub MCP tools       | GitHub API operations the MCP server offers, without a checkout.            | Attached to MCP requests outside the sandbox. The agent sees only results. |

A new agent turns GitHub MCP tools off with `disabled_integration_mcp_providers: ["github"]`, because most GitHub work runs in the sandbox. The grant still authenticates `git` and `gh`.

To turn GitHub MCP tools on, select **GitHub MCP tools** under the GitHub connection in the agent's **Integrations** section, then click **Save new version**. In the API, send a version whose `disabled_integration_mcp_providers` leaves out `github`. On a new version, leaving the field out entirely turns every provider's MCP tools on. See [Tools](/managed-agents/tools).

## Verify access

1. On **Integrations**, open the GitHub row's actions menu and click **Check**. A passing check means GitHub issued a token. The API response's `resource_count` is how many repositories the connection can reach.
2. Start a session and ask the agent to run:

   ```bash theme={"theme":"css-variables"}
   gh auth status
   git ls-remote https://github.com/acme/api.git HEAD
   ```

**What success means:** `git ls-remote` prints a commit hash for the repository. That proves network access, a token, and a grant that includes the repository. `gh auth status` alone doesn't prove repository access or write permission. To check write access, ask the agent to push a branch.

## Multi-agent sessions

Subagents share the root session's sandbox. A copy of the same agent inherits the parent's GitHub grant. A different agent from the roster uses only its own grants. See [Multi-agent](/managed-agents/multi-agent).

## Start work from GitHub

Connecting GitHub also adds a GitHub event source. An [automation](/managed-agents/automations) with a `github` trigger on that source starts a session when a matching event arrives, such as a pull request opened against `main` or an issue labeled `agent`. Filter by repository, action, branch, label, sender, and more, and give the automation an agent version that holds the GitHub grant.

```json theme={"theme":"css-variables"}
{
  "type": "github",
  "triggerId": "8b2e4d71-6c39-4a05-9f18-3d7a5c1e9b42",
  "enabled": true,
  "eventSourceId": "e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07",
  "events": ["issues"],
  "filters": { "repositories": ["acme/api"], "actions": ["labeled"], "addedLabels": ["agent"] }
}
```

The session's opening message is the automation's prompt followed by the GitHub event as JSON, so the agent knows which issue or pull request to work on. See [GitHub triggers](/managed-agents/automations#github).

If the event source's health is `setup_required`, the GitHub App is waiting for you to approve its event permissions. Approve the update in GitHub, then click **Check** on the connection.

## What can go wrong

| Symptom or code                                                            | Cause                                                                                                                   | Fix                                                               |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| "This organization has to approve the app before it can be connected."     | The GitHub organization requires owner approval.                                                                        | After an owner approves, start the connection again.              |
| The connection is **Suspended** or **Revoked**                             | The installation was suspended or uninstalled in GitHub.                                                                | Restore it in GitHub and click **Check**, or click **Reconnect**. |
| A check fails with `missing_permissions`                                   | The app has a pending permission request in GitHub.                                                                     | Accept the request in GitHub, then click **Check** again.         |
| `400 invalid_request` on `integration_connection_id` when saving the agent | The connection isn't active.                                                                                            | Check or reconnect it, then save.                                 |
| `400 invalid_request` on `integration_resources`                           | More than 500 repositories, or a name that isn't a repository.                                                          | Name fewer repositories as `owner/name`, or omit the list.        |
| `git` or `gh` is unauthenticated in the session                            | The agent version has no GitHub grant, or the session started before you saved it.                                      | Save the grant and start a new session.                           |
| `git` hangs or can't resolve `github.com`                                  | The environment's network policy blocks GitHub.                                                                         | [Allow the GitHub hosts](#allow-github-hosts).                    |
| A repository returns "not found"                                           | The repository isn't in the installation or in the grant's repository list. GitHub hides repositories you can't access. | Add it to the installation in GitHub and to the agent's grant.    |
| Push, comment, or rerun fails with a permission error                      | The grant is `read`, or the installation lacks that permission.                                                         | Grant `write`, and check the app's permissions in GitHub.         |
| GitHub MCP tools are missing                                               | `github` is in `disabled_integration_mcp_providers`.                                                                    | Turn on **GitHub MCP tools** and start a new session.             |

For all error codes, see [Errors](/managed-agents/errors).

## Limits

* A grant can list up to 500 repositories.
* An agent can hold up to 25 integration connections.

See [Limits](/managed-agents/limits) for every other limit.

## Next steps

<CardGroup cols={2}>
  <Card title="Integrations" href="/managed-agents/integrations">
    Connect, check, reconnect, and disconnect accounts.
  </Card>

  <Card title="Fix a GitHub issue" href="/managed-agents/use-cases/fix-a-github-issue">
    Walk through an agent that fixes an issue and opens a pull request.
  </Card>

  <Card title="Environments" href="/managed-agents/environments">
    Set up the sandbox and its network policy.
  </Card>

  <Card title="Vaults and credentials" href="/managed-agents/vaults">
    Grant GitHub per session, or add other secrets.
  </Card>
</CardGroup>