Version control

Eight tools covering the normal shape of agent work: branch, change, commit, push, open a pull request.

Every tool here takes _workspace and _sandbox — bind both. See Filling in tool parameters. Only the other parameters are listed below.

How an agent is meant to deliver work

ℹ️

Branch, commit, push, pull request. An agent never commits to your mainline — git_commit refuses a protected branch outright, and git_push refuses entirely when the project is set to pull-request-only. The rules come from your Code Workspace configuration.

Reading the repository

`git_status`

The working tree state: current branch, how far ahead or behind the remote, and which files are modified, added, deleted or untracked. Category: Data Pull.

Worth running before a commit, to see exactly what is about to be included.

`git_log`

Recent commits — sha, author, date, subject. Category: Data Pull.

The agent fills: limit, path (restrict history to one file or directory)

⚠️

A shallow clone has very little history. If git_log returns almost nothing, raise Clone depth on the Code Workspace — 0 fetches everything.

`git_diff`

What changed, in the working tree or between two revisions. Category: Data Pull.

The agent fills: staged, from_ref, to_ref, path, stat_only

stat_only returns only the per-file change counts, which is much smaller when an agent only needs the shape of a change. The output of this tool is also what parse_code_diff renders as a readable diff in chat.

Changing the repository

`git_branch_create`

Create a branch and check it out. Category: Action.

The agent fills: name — without the prefix
Optional: from_ref (omit to branch from the current HEAD)

The project’s Agent branch prefix — agent/ by default — is added for you, so agent work is identifiable at a glance.

`git_commit`

Stage and commit. Category: Action.

The agent fills: message, paths (omit to stage everything modified)
Pin if your repository enforces a committer identity: author_name, author_email — they default to qRaptor Agent and agent@qraptor.ai

Refuses to commit onto a protected branch. The commit is verified by reading back the new HEAD.

`git_pull`

Fetch and fast-forward the current branch. Category: Action.

ℹ️

This never merges. If the branches have diverged it reports the conflict and stops. A merge resolved without seeing the other side’s intent is worse than a clear refusal.

`git_push`

Push the current branch. Category: Action · Pauses for approval.

Bind: token
The agent fills: branch (omit to push what is checked out)
Optional: remote (origin unless the repository has several), set_upstream (leave on)

Refuses a protected branch, and refuses entirely when How agents deliver work is set to pull-request-only.

`git_pull_request_create`

Open a pull request from the current branch. Category: Action · Pauses for approval.

Bind: token, and organization_url for Azure DevOps
The agent fills: title, body, source_branch, target_branch, work_item_ids
Optional: draft, provider, repository, project

Only Azure DevOps and GitHub are supported. The provider is inferred from the remote URL unless you set it.

⚠️

This tool runs inside qRaptor, not on your executor — it calls the provider’s web API, so there is no checkout to be near. For Azure DevOps Services (dev.azure.com) that is fine. An on-premises Azure DevOps Server reachable only inside your network cannot be called this way; clone, push, build and test still work, because those run on your executor.

Common issues

A commit is refused — The checked-out branch is protected. Create a branch first.
A push is refused and no branch is named — The project is set to pull-request-only. Open a pull request instead.
git_log returns one commit — Shallow clone. Raise Clone depth.
A pull request call cannot reach your server — On-premises Azure DevOps Server is not reachable from qRaptor. See the warning above.
A pull stops reporting a conflict — Deliberate. The branches diverged, and nothing is merged automatically.