GitHub access

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.

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.
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.

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

In the sidebar, click Integrations, then click Add integration.
Choose GitHub and click Continue.
On GitHub, choose the organization or user account and the repositories the app can reach. Approve the installation.
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.

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.

Console
TypeScript
cURL

Open the agent. On Configuration, find Integrations and click Add integration access.
Click Select next to the GitHub connection.
Set Access level to Read only, Read and write, or Full: everything the installation allows.
Clear All authorized repositories and pick the repositories, or keep it to cover the whole installation.
Click Use this access, then click Save new version.

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'],
  },
});

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"]
  }'

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. To give different sessions of the same agent different repositories or accounts, grant GitHub through a vault instead. See Grant through a vault.

Allow GitHub hosts

A GitHub grant supplies a credential, not network access. If the environment’s network policy 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.

Verify access

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.

Start a session and ask the agent to run:

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.

Start work from GitHub

Connecting GitHub also adds a GitHub event source. An automation 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.

{
  "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. 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.
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.

Limits

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

See Limits for every other limit.

Next steps

Integrations

Connect, check, reconnect, and disconnect accounts.

Fix a GitHub issue

Walk through an agent that fixes an issue and opens a pull request.

Environments

Set up the sandbox and its network policy.

Vaults and credentials

Grant GitHub per session, or add other secrets.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Before you begin

What limits a session’s access

Connect GitHub

Grant GitHub to an agent

Allow GitHub hosts

How the token reaches git and gh

Choose sandbox or MCP tools

Verify access

Multi-agent sessions

Start work from GitHub

What can go wrong

Limits

Next steps

Integrations

Fix a GitHub issue

Environments

Vaults and credentials

​Before you begin

​What limits a session’s access

​Connect GitHub

​Grant GitHub to an agent

​Allow GitHub hosts

​How the token reaches git and gh

​Choose sandbox or MCP tools

​Verify access

​Multi-agent sessions

​Start work from GitHub

​What can go wrong

​Limits

​Next steps

Integrations

Fix a GitHub issue

Environments

Vaults and credentials

Before you begin

What limits a session’s access

Connect GitHub

Grant GitHub to an agent

Allow GitHub hosts

How the token reaches git and gh

Choose sandbox or MCP tools

Verify access

Multi-agent sessions

Start work from GitHub

What can go wrong

Limits

Next steps