GitHub repositories
Mount a Git repository into a session sandbox in Orca Agent Engine and give the agent GitHub tools through an MCP server.
Giving an agent access to a repository has two halves, and they are configured in different places. Mounting the code is a session resource: the repository is cloned into the session sandbox, where the built-in read, edit, and bash tools can work on it. Acting on GitHub - opening pull requests, commenting on issues - comes from an MCP server declared on the agent.
There is no agent-level GitHub configuration. Repositories attach to sessions, so the same agent can work on different repositories in different sessions.
Get your registry endpoint
Registry endpoint
Examples on this page target your registry endpoint - the deployment host root, with no path
suffix. For CLI, set ORCA_REGISTRY_URL and exactly one of ORCA_ACCESS_TOKEN (Bearer) or
ORCA_API_KEY (x-api-key). For TypeScript SDK, set ORCA_BASE_URL / ORCA_API_KEY (Bearer).
To find the endpoint, see Connect to the registry.
Repository resource fields
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | github_repository. |
url | string | Yes | Repository URL. Must be https:// with at least an owner and repository path segment. Not restricted to github.com - any HTTPS Git host works. |
authorization_token | string | Yes | Token used to clone. Write-only: never returned by any endpoint. |
mount_path | string | No | Where to mount in the sandbox. Defaults to /workspace/<repo>/. Must be an absolute path and must not overlap /workspace/skills; both are enforced. Uniqueness is not - duplicates are rejected only among memory stores, so two repositories can be given the same path and nothing stops them. |
access | string | No | read_only or read_write. Defaults to read_write. |
instructions | string | No | Stored and returned, but never reaches the agent - nothing reads it. Put repository guidance in the system prompt instead. Up to 4096 characters. |
checkout | object | No | {"type": "branch", "name": "..."} or {"type": "commit", "sha": "..."}. See the note below. |
A session can mount at most 8 repositories. The same repository URL cannot be mounted twice in one session.
/workspace/skills is reserved for the skills tree, and repositories mount under /workspace/ by default - so a repository whose last URL segment is skills collides with it. The registry rejects any mount_path that overlaps that root, after normalizing .. and duplicate slashes, with mount_path must not overlap reserved Skill root /workspace/skills. Set an explicit mount_path for such a repository.
Mount a repository
Attach repositories when you create the session. $GITHUB_TOKEN and $NEW_GITHUB_TOKEN are tokens you supply from your own environment, with the scopes listed under Token permissions. $AGENT_ID is the agent you are running - the GitHub-tool agent below, or any agent - and $ENVIRONMENT_ID is an environment. The later examples on this page need the new session's ID, so capture it:
session=$(ork agent sessions create \
--agent "$AGENT_ID" \
--environment-id "$ENVIRONMENT_ID" \
--resource-json '{
"type": "github_repository",
"url": "https://github.com/acme/billing-service",
"mount_path": "/workspace/billing",
"authorization_token": "'"$GITHUB_TOKEN"'"
}' \
-o json)
SESSION_ID=$(jq -r '.id' <<< "$session")The clone is shallow and blobless by default, so large repositories mount quickly. Pinning a commit forces a full-history clone.
The token is used on the Agent Engine host to perform the clone and is never written into the sandbox, so the agent cannot read it out of the filesystem or the Git remote configuration.
The checkout field is accepted by the registry but is not reliably applied. The API, CLI, and SDK all send {"type": "branch", "name": ...} while the component that performs the clone reads a differently-named field, and no translation between the two exists. Treat the checked-out ref as the repository's default branch until this is resolved, and have the agent switch branches with git in the sandbox if it needs a specific ref.
Mount several repositories by adding entries:
{
"resources": [
{
"type": "github_repository",
"url": "https://github.com/acme/frontend",
"mount_path": "/workspace/frontend",
"authorization_token": "..."
},
{
"type": "github_repository",
"url": "https://github.com/acme/backend",
"mount_path": "/workspace/backend",
"access": "read_only",
"authorization_token": "..."
}
]
}Give the agent GitHub tools
Mounting a repository gives the agent the files. To open pull requests or read issues, declare a GitHub MCP server on the agent and reference it from an mcp_toolset. Both halves are required - a declared server with no matching toolset entry returns 400.
ork agent create \
--name "code-reviewer" \
--model claude-sonnet-4-6 \
--system "You review code and open pull requests with focused changes." \
--mcp-server name=github,type=url,url=https://api.githubcopilot.com/mcp/ \
--tool-json '{"type":"agent_toolset"}' \
--tool-json '{"type":"mcp_toolset","mcp_server_name":"github"}'The agent definition holds the server URL but no token. MCP servers authenticate through vault credentials bound to the server's URL, which is separate from the repository's authorization_token. Because MCP toolsets default to always_ask, the agent pauses for your approval before its first GitHub write - see Permission policies.
Token permissions
Grant the narrowest scopes that let the agent do its job:
| Action | Required scope |
|---|---|
| Clone a private repository | repo |
| Open pull requests | repo |
| Read issues | repo for private, public_repo for public |
Use fine-grained personal access tokens scoped to the specific repositories the agent needs. A classic token with broad repo scope grants the agent every repository the token's owner can reach, not just the mounted one.
GitHub tokens are held in a credential store separate from vaults, and are bound to the resource that supplied them. There is no GitHub App installation flow and no OAuth flow - supply a token.
Rotate a token
Repositories can be attached to and detached from a live session: POST /v1/sessions/{sessionId}/resources takes type: "github_repository", and DELETE /v1/sessions/{sessionId}/resources/{resourceId} removes one. The ork CLI exposes the same through sessions resources add --type github-repository. You can also replace an expiring token in place - list the session's resources to find the resource ID, then update it:
resources=$(ork agent sessions resources list --session "$SESSION_ID" -o json)
RESOURCE_ID=$(jq -r '.data[] | select(.type == "github_repository") | .id' <<< "$resources")
ork agent sessions resources update "$RESOURCE_ID" \
--session "$SESSION_ID" \
--authorization-token "$NEW_GITHUB_TOKEN"To change which repositories are mounted, attach or detach them on the session's resources sub-resource; you do not need a new session.
Permissions
Repository mounts are session resources. Treat every Workspace API key as full access to its Workspace's resources, and separate access with Workspaces. See Control registry access.