GitHub access

A GitHub connection gives an agent two surfaces with one short-lived GitHub App installation token per session: the GitHub MCP tools, which run outside the sandbox, and authenticated git, Git LFS, and gh inside the sandbox for cloning, building, testing, and pushing. Both use the same permissions and repository scope. Where a deployment restricts sandbox GitHub access, only the MCP tools are available and the agent is told to use them instead of git and gh.

​

Connect GitHub

1. In Integrations, click Add integration, then choose GitHub. Authorize the GitHub user so Recursion can find the App installations that user can access.
2. Choose an existing installation, or choose Install on another account and select the account and repositories in GitHub. If none are available, Recursion starts installation automatically. For an existing installation, use Manage repositories on GitHub to change its repository access in a separate tab. Return to Recursion and click Continue to connect with the updated access. Choosing an already installed account on GitHub’s App installation page opens its settings without returning to Recursion.
3. Back in Integrations, select the tools available to the organization and save. The picker describes each tool and groups the current GitHub tools as Read-only or Changes data. Merging a pull request changes data; the Destructive category is reserved for tools that delete data, and none of the current GitHub tools do so. Use the group checkboxes or Select read-only, Select all, and Clear to choose several at once. You can change this selection later with Edit tools on the connection.

The App’s installed permissions are fixed by its configuration. Choosing tools in Recursion narrows which MCP calls agents can make and which permissions their short-lived tokens request. It does not change the App installation’s permissions in GitHub. New connections start with the supported read tools; connections created before tool selection have all supported tools enabled. The tool list comes from the production App’s permissions. The connection’s tool selection is a ceiling for every agent that uses it. Workflow-file editing is unavailable. To change repository access after connecting, open the installation’s settings in GitHub, save the new selection, then use Reconnect on the GitHub connection in Recursion. Reconnecting refreshes the repositories available through that connection while preserving agent grants.

​

Assign GitHub to an agent

1. In the agent’s Integrations section, click Add integration access and select the GitHub connection.
2. In Tools, review each tool’s description and read-only or write classification. Use Select read-only, Select all, Clear, or the group checkboxes to choose a subset of the connection’s tools.
3. In Repositories, choose specific repositories or All authorized repositories.
4. Click Use this access, then save the agent version.

The agent’s GitHub token requests the permission categories required by its selected tools, for the MCP tools and for git and gh in the sandbox alike. There is no separate read/write token setting in standalone Managed Agents. Existing agent grants without a tool list retain their former read or write tool scope, subject to the connection’s current tool ceiling. Repository selections can only narrow the repositories installed in GitHub. If an administrator removes a tool from the connection, the agent’s saved selection still shows it as unavailable. Edit the agent’s GitHub access and uncheck the unavailable tool. To keep the access, select at least one available tool; otherwise, use Remove access. New sessions can use only tools still enabled for the connection. When using the API, set nativeIntegrations[].tools to the selected tool names. The permission field remains in the version contract for compatibility; the server derives its read or write value from the tools. You can discover supported tools through listIntegrationProviders and the connection’s enabled tools through listIntegrationConnections. Templates name their GitHub tools, and an agent created from a template, from the Agents page or through the assistant’s Use template, receives that list. The PR reviewer reads pull requests, files and issues and writes pull request reviews, so its token carries pull request write permission and no permission to change contents or issues; the Issue fixer also creates branches, pushes files and opens pull requests. The setup form and the approval card list the tools and what their write permissions allow. If the connection does not enable one of a template’s tools, setup stops before anything is created and names the tools to enable on Integrations. A new agent version or connection selection applies to new sessions. A new agent version also applies to a running session you move to it. Running sessions may keep credentials and tool lists they already received until they refresh or end. Name repositories as owner/name, up to 500, where owner is the connection’s own account. A repository of another owner is refused; grant it through the connection for that owner. A new agent version replaces the whole definition, so include every field you want to keep.

​

Use git and gh in the sandbox

Depending on the deployment, the sandbox holds either the token itself or only a placeholder that Recursion replaces with the real token on the way to github.com and api.github.com, outside the sandbox; with a placeholder, nothing in the sandbox, including git credential fill, can read the token, and everything below about using git and gh still applies. When the sandbox holds the token, it reaches git, Git LFS, and gh through the sandbox’s credential helper, not through an environment variable: an agent that checks GITHUB_TOKEN finds nothing, but git clone, git push, and gh pr create against a granted repository authenticate. The token expires about an hour after it was issued. The platform refreshes it for subsequent sandbox commands, but a long-running command can outlive its token, and requesting credentials again inside that command does not renew it; run a long clone or LFS transfer as its own command. Any command in the sandbox can use the token, including commands an agent runs on untrusted input. The tool selection narrows the token’s GitHub permission categories and the repository selection narrows its repositories, but inside the sandbox the token allows every operation those categories permit, not only the selected tools: selecting create_pull_request alone still lets gh pr edit and gh pr close run on pull requests in the granted repositories, and push_files alone still lets git push --force run where the repository’s rules allow it. The per-tool allowlist applies to the MCP tools only. Grant only the repositories, and the permission categories, the agent needs. When a session starts on new compute, Recursion adds the GitHub hosts to an environment policy that allows specific hosts, so a grant that reaches the sandbox works without listing them; see Hosts common tools need. An environment with No access stays closed: switch its Internet access on, or allow the hosts, before git can reach GitHub. The hosts are added only when a sandbox is created; a session resumed on a running sandbox keeps the policy it started with, so start a new session after changing the grant. GitHub MCP calls run outside the sandbox and need no host allowlist.

​

Verify access

Open the connection’s actions menu and click Test connection. Then start a new agent session and ask it to use one of the selected GitHub tools, or to run git ls-remote against a granted repository. A passing connection test proves GitHub issued a token; a successful tool call or clone also proves that the tool, repository, and permission were available.

​

More information

See Integrations for connection states and Tools for MCP tool use.