github-repo

name	github-repo
description	Native GitHub repository management in your workspace. Clone public/private repos, create branches, commit, push, and open PRs. Use for any GitHub remote work — including repos already present under repos/<name>. Acquire when the user asks for GitHub PRs, branches, pushes, or external/multi-repo projects (do not rely on raw git in tool.cli for this).
toolbox	{"source":"toolbox/devtools/toolbox.yaml","tools":["github-repo"]}

GitHub Repo

Problem

The repo-git tool manages platform-hosted artifact repos via file:// protocol. It cannot clone arbitrary GitHub repositories. When a user asks you to work on an external codebase — a public open-source project, a private company repo, or a multi-repo setup across different GitHub orgs — repo-git does not help.

Why use github-repo instead of raw git in tool.cli

• tool.cli is policy-gated — long shell pipelines (find, sed, chained discovery) are often not on the CLI allowlist. The github-repo tool runs approved git operations without fighting that policy.
• Commit identity — the github-repo helper exports GIT_AUTHOR_* / GIT_COMMITTER_* so commit succeeds. Raw git commit via tool.cli may fail with “Author identity unknown” unless the environment sets identity elsewhere.
• Paths — workspace root is $AGENT_WORKSPACE (commonly /workspace in containers). Use repos/<name>/ relative to workspace for workspace.read / workspace.write. Do not assume /mnt/workspace/... or other host paths.
• Push auth — pushes need GITHUB_TOKEN / GH_TOKEN or SSH keys mounted for the sandbox. github-repo push uses the same auth wiring as clone; raw git push to https://github.com/... fails the same way if auth is missing, but github-repo fails fast with a clear message.

Solution: github-repo Tool

The github-repo toolbox tool clones and manages GitHub repositories directly in your workspace over HTTPS or SSH. Authentication is handled automatically via environment variables — you never need to configure credentials yourself.

Commands

Command	Purpose
github-repo clone <url> [--name <dir>] [--branch <b>]	Clone a repo into $AGENT_WORKSPACE/repos/<name>/
github-repo pull [<repo>]	Pull latest changes
github-repo push [<repo>] [--branch <b>]	Push committed changes
github-repo commit [<repo>] --message <msg>	Stage all changes + commit
github-repo status [<repo>]	Show git status
github-repo list	List all cloned repos with branch and status
github-repo branch [<repo>] [--create <name>]	List or create branches
github-repo pr create [<repo>] --title <t> [--body …] [--base …] [--head …]	Create a PR via gh (after push; on failure prints a browser URL)
github-repo pr url [<repo>]	Print https://github.com/org/repo/pull/new/<branch>
github-repo gh [<repo>] -- <gh-args>…	Passthrough gh with repo as working dir (reviews, issues, etc.)
github-repo remove <repo>	Delete a repo from workspace

When <repo> is omitted and only one repo is cloned, it is used automatically. When multiple repos exist, you must specify which one.

Pull requests and gh (prefer the toolbox)

Default: open and manage PRs with devtools.github-repo (pr create, pr url, gh … --). That runs in the devtools sidecar and is not subject to the same tool.cli allowlist as interactive shell.

tool.cli policy gotcha: allowlists classify by the first shell token. A command like cd … && gh pr create … is classified as cd, which is often not allowlisted — the denial happens before gh runs. Similarly, gh must appear on the world’s CLI tier list to be used as the first token from tool.cli.

If you use raw gh in tool.cli: use a single invocation whose first token is gh, e.g. gh -R org/repo pr create --title "…" --body "…" (from any cwd), not cd … && gh ….

Workspace Layout

$AGENT_WORKSPACE/
├── repos/
│   ├── my-app/          ← cloned from GitHub
│   ├── shared-lib/      ← cloned from GitHub
│   └── ...
├── artifact-repo/       ← repo-git managed (if enabled)
└── ...

Authentication

Authentication is auto-detected. You do not configure it — the platform sets environment variables on the container.

Mode	Condition	Behavior
Token (HTTPS)	GITHUB_TOKEN env var is set	All URLs (including git@ SSH format) are handled via HTTPS + token. GH_TOKEN is mirrored from GITHUB_TOKEN (and vice versa) so gh sees a token.
SSH	SSH key mounted at /etc/github-ssh/	[e-mail]:... URLs work natively.
Public only	Neither token nor SSH	Clone works for public repos. Push/PR operations will fail with a clear error.

You can check which mode is active by looking at the output of github-repo clone — it will say whether it used HTTPS or SSH.

Workflows

Single Repo

github-repo clone https://github.com/org/my-app.git
# ... edit files via workspace.write or coding agents ...
github-repo commit --message "fix: resolve auth redirect loop"
github-repo push

Python / caches: github-repo commit runs git add -A. Add a .gitignore (e.g. __pycache__/, *.pyc) so bytecode and other junk are not committed.

Multi-Repo Project

github-repo clone https://github.com/org/frontend.git
github-repo clone https://github.com/org/backend-api.git
github-repo list
# Work on each repo by name:
github-repo status frontend
github-repo commit backend-api --message "add CORS headers"
github-repo push backend-api

Feature Branch + PR

github-repo clone https://github.com/org/my-app.git
github-repo branch my-app --create feature/new-auth
# ... make changes ...
github-repo commit my-app --message "feat: add OAuth2 login flow"
github-repo push my-app --branch feature/new-auth
github-repo pr create my-app --title "feat: OAuth2 login" --body "Adds OAuth2..."
# If pr create fails, the tool prints a https://github.com/org/repo/pull/new/... URL — open it in a browser.
# Optional: github-repo pr url my-app   # print that URL without calling gh

If the repo is already in the workspace (e.g. user context says repos/my-app), skip clone — use github-repo list / github-repo status my-app, then github-repo branch, workspace.write, github-repo commit, github-repo push, then github-repo pr create or github-repo pr url.

Code Review (clone a PR branch)

github-repo clone https://github.com/org/my-app.git --branch feature/fix-bug
# Read and review code via workspace.read
github-repo gh my-app -- pr review 42 --comment --body "LGTM with one nit..."

Delegate to Coding Agents

After cloning, delegate large edits to cursor-agent or claude-agent:

github-repo clone https://github.com/org/my-app.git
cursor-agent --folder $AGENT_WORKSPACE/repos/my-app --prompt "refactor the auth module to use middleware pattern"
github-repo status my-app
github-repo commit my-app --message "refactor: auth middleware pattern"
github-repo push my-app

Contracts

Do

• Use github-repo for clone, branch, commit, push, PRs, and gh passthrough on GitHub remotes (including repos already under repos/<name>/). Prefer it over git ... inside tool.cli for that workflow.
• Use github-repo pr create, github-repo pr url, or github-repo gh <repo> -- … for PR and review flows — not cd … && gh … in tool.cli (first token cd is often denied).
• If you must use gh in tool.cli, use gh as the first token, e.g. gh -R org/repo pr create …. Never pass a filesystem path to gh -R; use org/repo.
• Specify repo name when multiple repos are cloned.
• Use github-repo remove to clean up repos you no longer need.

Do Not

• Do not store tokens, keys, or credentials in workspace files.
• Do not use git config --global to set credentials — auth is handled automatically. (If you must set a local display name for a rare raw-git path, use git config in that repo only — prefer github-repo commit instead.)
• Do not clone repos outside of $AGENT_WORKSPACE/repos/ — the tool enforces this path.
• Do not assume push access — if no token or SSH key is configured, push will fail.
• Do not chain many shell commands in one tool.cli for repo discovery — use workspace.read, github-repo status, or github-repo list.

Error Handling

Error	Cause	Recovery
command not in CLI policy allowlist	First token of tool.cli not allowlisted (e.g. cd in cd && gh, or gh not on tier list)	Use github-repo pr create / github-repo gh … -- / github-repo pr url; or one gh -R org/repo … if gh is allowlisted
cannot change to '/mnt/workspace/...' (or similar)	Wrong workspace path	Use $AGENT_WORKSPACE / repos/<name> — not /mnt/workspace
"Author identity unknown"	Raw git commit without author env	Use github-repo commit (sets author) or local git config user.* once in repo
"could not read Username for 'https://github.com'"	Push without token / SSH	Platform must set GITHUB_TOKEN or SSH; report to user
"directory already exists"	Repo name collision	Use --name <alternate> to clone with a different directory name
"Push requires authentication"	No GITHUB_TOKEN or SSH key configured	Report to user — this is a platform configuration issue
"no repo ... at ..."	Typo in repo name argument	Run github-repo list to see available repos
"multiple repos exist"	Repo name omitted with 2+ repos cloned	Specify the repo name explicitly
Clone fails with 404	Repo is private and no auth configured, or URL is wrong	Verify URL; check if authentication is available

When NOT to Use

• Platform artifact repos — use repo-git for repos managed by the artifact system.
• Non-GitHub remotes — for GitLab, Bitbucket, or self-hosted Git, use raw git via tool.cli.
• Submodule operations — use tool.cli with native git submodule commands.