Git

View as Markdown

A RocketRide tool node that exposes git repository operations to an AI agent.

What it does

Gives an agent safe, full-featured access to a git repository. The agent can open an existing local repository, clone a remote one, or initialize a fresh one, then work with the complete toolset: status and logs, diffs, staging and commits, branches, remotes, and history search.

Uses pygit2 / libgit2: the libgit2 native library is bundled inside the pygit2 wheel, so no host git binary is required on the machine running the engine.

Write operations are guarded by two toggles, both on by default: read-only mode blocks all writes, and safe mode blocks force-push and force branch deletion. A freshly added node can only inspect a repository until you turn read-only mode off.

---

Configuration

Field	Type	Description
repoPath	string	Default empty. Local path to an existing repository, or a remote URL (https://, git@, ssh://). A remote URL is cloned into a temporary directory at pipeline start and cleaned up on exit. Leave blank to let the agent call clone or init at runtime.
authType	string	Default "none". How to authenticate with remote repositories.
username	string	Default empty. Git username for token-based HTTPS authentication.
token	string	Default empty. Personal access token or password for HTTPS authentication. Leave empty when using SSH.
sshKey	string	Default empty. PEM-encoded SSH private key content (starts with -----BEGIN ...). Used when Auth Type is SSH.
sshPassphrase	string	Default empty. Passphrase for the SSH private key, if encrypted. Leave empty for unencrypted keys.
safeMode	boolean	Default true. Block destructive operations: force-push and force branch deletion. Normal branch deletion is allowed only when the branch is fully merged into HEAD; deleting an unmerged branch requires force=true (which is blocked in safe mode). Recommended for agent use.
readOnlyMode	boolean	Default true. Block ALL write operations (clone, init, write_file, stage, commit, stash push/pop/drop, branch create/delete, checkout, merge, fetch, pull, push). Read-only tools (status, log, show, diff, blame, file_at, branch_list, grep, ls_files, stash list) remain available. Strictly stronger than Safe Mode. Recommended when the agent only needs to inspect a repository.

repoPath: local path vs remote URL

repoPath is interpreted differently depending on its value:

Value	Behaviour
Remote URL (https://, http://, git://, git@, ssh://)	The repository is cloned into a temporary directory when the pipeline starts. The temp directory is deleted automatically when the pipeline ends. Use this for read-only analysis or ephemeral write workflows.
Local path	The existing directory is opened in place. No copy is made. Changes made by the agent persist on disk.
Empty	No repository is opened at startup. The agent must call clone or init as its first action.

Note: when using a remote URL with write operations (push), ensure authType and credentials are configured, since the cloned temp repo retains the remote origin from the URL.

---

Available tools

Repository

| Tool | Description | |---|---|---| | clone | Clone a remote git repository to a local path. Returns clone summary including the checked-out branch and HEAD SHA. | | init | Initialise a new empty git repository at the given path. Creates the directory if it does not exist. | | status | Return the working-tree status: current branch, staged files, unstaged modifications, and untracked files. | | log | Return commit history. Supports filtering by branch, file path, author name, and date range. | | show | Show full details of a single commit: metadata, diff patch, and file-change statistics. | | diff | Produce a unified diff. Can diff working tree vs HEAD, two refs, or the staged index vs HEAD. | | blame | Return per-line blame for a file: which commit and author last modified each line. | | file_at | Return the raw content of a file at a specific commit or ref. | | write_file | Write text content to a file in the working tree (creates or overwrites). Call stage then commit after writing to save the change. | | stage | Stage files for the next commit (equivalent to git add). Deleted files are removed from the index. | | commit | Create a commit from the current staged index. | | stash | Manage the git stash. Operations: push, pop, list, drop. | | branch_list | List local branches, and optionally remote-tracking branches. | | branch_create | Create a new branch, optionally from a specific ref. | | checkout | Check out an existing local branch. | | branch_delete | Delete a branch. Normal deletion is always allowed. Force deletion (force=true) is blocked when safeMode=true. | | merge | Merge a branch into the current branch. Fast-forwards if possible, otherwise creates a merge commit. Raises on conflicts. | | fetch | Fetch updates from a remote without merging. | | pull | Fetch from a remote and fast-forward merge the current branch. | | push | Push the current (or specified) branch to a remote. Force-push is blocked unless safeMode=false. | | grep | Search tracked file contents for a regex pattern. Returns file, line number, and matching line for each hit. Capped at max_results hits to keep responses bounded. | | ls_files | List all tracked files in the repository, optionally filtered by path prefix. |

Status & info

Tool	Description
status	Working-tree status: staged, unstaged, untracked files
log	Commit history with optional filters
show	Full details + diff for a single commit

Diff & inspection

Tool	Description
diff	Unified diff (working tree, two refs, or staged)
blame	Per-line blame for a file
file_at	File content at a specific commit or ref

Working tree & commits

Tool	Description
write_file	Write text content to a file in the working tree (creates or overwrites)
stage	Stage files (git add)
commit	Create a commit from staged index
stash	Push / pop / list / drop stash

Branches

Tool	Description
branch_list	List local (and/or remote) branches
branch_create	Create a branch from any ref
checkout	Check out an existing branch
branch_delete	Delete a branch
merge	Merge a branch into the current one

Remote

Tool	Description
fetch	Fetch from a remote
pull	Fetch + fast-forward merge
push	Push to a remote (force-push blocked in safe mode)

Search

Tool	Description
grep	Regex search across tracked file contents
ls_files	List tracked (and optionally untracked) files

---

Safe mode

When safeMode is true (the default), the following operations raise an error instead of executing:

• force push: push with force: true
• force branch deletion: branch_delete with force: true

Normal branch deletion (force: false) is not gated by safe mode, but it only succeeds when the branch is fully merged into HEAD; deleting an unmerged branch requires force: true, which safe mode blocks. In practice, an unmerged branch cannot be deleted while safe mode is on.

Set safeMode: false in the node config to allow force operations.

Security note: write scope

Safe mode does not restrict file writes. Anything outside the .git/ directory is fair game for write_file, including .gitignore, CI configs, build scripts, source files, and lockfiles. Path traversal (../) and writes inside .git/ are blocked, but otherwise the agent has full read/write access to the working tree.

When pointing the node at a real repository (rather than a remote URL that auto-clones into a temp directory), treat the agent as a human contributor with commit rights to that tree. If you need stricter scoping, run the agent against a temp clone or a sandboxed working copy.

---

Read-only mode

When readOnlyMode is true (the default), every mutating tool is blocked at dispatch and returns a JSON error. This is strictly stronger than safeMode and is the recommended setting when the agent only needs to inspect a repository.

Blocked tools: clone, init, write_file, stage, commit, stash (op push / pop / drop), branch_create, checkout, branch_delete, merge, fetch, pull, push.

Always allowed: status, log, show, diff, blame, file_at, branch_list, grep, ls_files, and stash with op: "list".

Set readOnlyMode: false in the node config to allow write operations (subject to safeMode).

---

Authentication

Token (HTTPS)

Set authType: token, then provide username (e.g. "git" for GitHub/GitLab) and token (personal access token or app password).

SSH

Set authType: ssh, then paste the PEM-encoded private key content into sshKey. If the key has a passphrase, set sshPassphrase as well.

The key content is written to a temporary file with chmod 0400 during remote operations and deleted immediately after.

---

Running the tests

# Unit tests only (no git binary or real repo needed)
pytest nodes/test/tool_git/test_tools.py -v

# Integration tests against a real local repository
export GIT_TEST_REPO_PATH=/path/to/any/local/git/repo
pytest nodes/test/tool_git/test_tools.py -v

---

Schema

Field	Type	Description	Default
git.authType	string	Authentication Type How to authenticate with remote repositories.	"none"
git.readOnlyMode	boolean	Read-Only Mode Block ALL write operations (clone, init, write_file, stage, commit, stash push/pop/drop, branch create/delete, checkout, merge, fetch, pull, push). Read-only tools (status, log, show, diff, blame, file_at, branch_list, grep, ls_files, stash list) remain available. Strictly stronger than Safe Mode. Recommended when the agent only needs to inspect a repository.	true
git.repoPath	string	Repository Path Local path to an existing repository, or a remote URL (https://, git@, ssh://). A remote URL is cloned into a temporary directory at pipeline start and cleaned up on exit. Leave blank to let the agent call clone or init at runtime.	""
git.safeMode	boolean	Safe Mode Block destructive operations: force-push and force branch deletion. Normal branch deletion is allowed only when the branch is fully merged into HEAD; deleting an unmerged branch requires force=true (which is blocked in safe mode). Recommended for agent use.	true
git.sshKey	string	SSH Private Key PEM-encoded SSH private key content (starts with -----BEGIN ...). Used when Auth Type is SSH.	""
git.sshPassphrase	string	SSH Key Passphrase Passphrase for the SSH private key, if encrypted. Leave empty for unencrypted keys.	""
git.token	string	Token / Password Personal access token or password for HTTPS authentication. Leave empty when using SSH.	""
git.username	string	Username Git username for token-based HTTPS authentication.	""

Dependencies

• pygit2 >=1.19.2