Git Integration

Each project workspace supports git version control for tracking changes made by agents and users.

Where the Git Panel Lives#

The Git panel is embedded in the Files tab of the left sidebar inside the Command Center. Click the Git toggle at the top of the Files tab to expand it. The current branch is displayed in the toggle button header when a repository is initialized.

The branch name also appears in the status bar at the bottom of the workspace and is clickable — opening the Branch Picker for switching and syncing branches without leaving the editor.

Initializing a Repository#

When no git repository exists in the workspace, the Git panel offers two options:

  • Initialize Git — Creates a new local repository (git init) in the project workspace directory.
  • Clone Repository — Clones a remote repository into an empty workspace. Only available when the workspace is empty. Requires an SSH key configured in your profile (see SSH Key Setup).

Supported Remote Hosts#

For security reasons, remote URLs are validated against an allowlist of public git providers. Accepted hosts:

  • github.com
  • gitlab.com
  • bitbucket.org
  • codeberg.org
  • git.sr.ht

Both SSH (git@host:org/repo.git) and HTTPS (https://host/org/repo.git) URL formats are accepted for configuration. Clone, fetch, push, and pull operations always use the SSH key in your profile.

Viewing Status#

The Git panel shows files grouped into two sections:

  • Staged — Files ready to commit (index status is not a space or ?)
  • Changes — Unstaged modifications and untracked files

Git status updates automatically via the Project WebSocket. The server polls the workspace every 10 seconds while any client is subscribed to the git topic, and pushes updates only when the status changes. When the WebSocket is disconnected, status reverts to the last REST response.

The status bar also displays ahead/behind commit counts relative to the upstream branch (e.g. ↓1 ↑2) and a diff stat showing net insertions and deletions (+N -N) across all uncommitted changes.

Inspecting Changes#

File-Level Diff#

Click any file path in the Git panel's Staged or Changes sections to open a side-by-side diff in the right panel editor. The diff shows the file at HEAD on the left and the current working-tree version on the right.

File-Level Status#

Each file shows its two-character porcelain status code (e.g. M for modified, A for added, ?? for untracked).

Committing#

  1. Stage individual files — Click + next to any file in the Changes section to stage it.
  2. Stage all — Click the + button in the Changes section header to stage all changed files at once.
  3. Unstage individual files — Click − next to a staged file.
  4. Unstage all — Click the − button in the Staged section header.
  5. Commit — Type a commit message (max 1 000 characters) and click Commit or press Enter.

Control characters are stripped from commit messages. Empty messages are rejected.

Branch Management#

The Branch Picker is accessible from the status bar (click the branch name) or from the Branch Picker popover. It provides:

  • Switch branch — Click any listed local or remote branch to switch.
  • Create branch — Type a new branch name in the search box and select Create "…".
  • Fetch / Pull / Push — Buttons in the Branch Picker footer sync with the configured remote. These require an SSH key and a remote URL; see Remote Operations below.

Branch names may only contain alphanumeric characters, /, _, ., and -.

Commit History#

Click History in the Git panel to load and display the commit log. Each entry shows:

  • Abbreviated commit hash (7 characters)
  • Author name
  • Commit date
  • Commit message subject

The log fetches the most recent 20 commits by default.

Agent Checkpoints and Revert#

Before each execution turn begins, the platform automatically captures the current HEAD SHA as a named checkpoint in the execution event log (labels pre_execute and turn_0). If the workspace is a new repo with no commits yet, the capture is a no-op.

You can roll the workspace back to a named checkpoint via:

POST /api/executions/{execution_id}/revert
{ "label": "pre_execute" }

The endpoint performs a git reset --hard to the SHA recorded under that label and returns the resolved commit_sha. This lets you undo all file changes an agent made during a run without manually inspecting the diff or crafting a revert commit. Note that git reset --hard discards uncommitted changes — only checkpointed (committed) state can be restored via this path.

Remote Operations#

Clone, fetch, pull, and push all require:

  1. An SSH key configured in your profile (Profile > Security tab → SSH Key section).
  2. A remote URL configured for the project (Project Settings → Git Configuration, or set automatically when you clone).

Fetch#

Runs git fetch --prune using your SSH key. Updates remote-tracking refs and prunes stale ones. Times out after 60 seconds.

Pull#

Runs git pull --ff-only. Only fast-forward merges are performed; diverged branches require a manual rebase or merge in the terminal. Times out after 60 seconds.

Push#

Runs git push origin HEAD. Times out after 60 seconds.

SSH Key Setup#

SSH keys are stored per-user (not per-project). To set one up:

  1. Open Profile from the user menu.
  2. Go to the Security tab.
  3. Under SSH Key, click Generate SSH Key to create a new Ed25519 key pair, or Import Existing Key to paste an existing Ed25519 private key (PEM format).
  4. Copy the displayed public key and add it as a deploy key (read/write) or user SSH key in your Git hosting provider.

Once a key is configured, all git remote operations across all your projects use this key automatically.

Project Git Configuration#

Each project has a git configuration record storing:

  • Remote URL — The upstream repository (SSH or HTTPS).
  • Default Branch — Used as the default when cloning without an explicit branch (defaults to main).

Edit these in Project Settings → Git Configuration. The remote URL is also set automatically when you clone from the Git panel.

Real-Time Updates#

The Project WebSocket subscribes to git status updates. The client sends a subscribe message with topics: ["git", "files", "executions", "indexing"]; the server then starts polling the workspace every 10 seconds and publishes updates to the project:<id>:git Redis channel whenever the status hash changes. Updates include branch, file statuses, ahead/behind counts, and diff stat (insertions/deletions).

Troubleshooting#

"No SSH key configured" error on clone/fetch/push/pull. Add an SSH key under Profile → Security → SSH Key before using remote operations.

"No remote repository configured" error. Set a remote URL in Project Settings → Git Configuration, then retry.

Clone fails with "Workspace is not empty". The clone operation requires an empty workspace. Delete or move existing files via the terminal before cloning.

Push/pull rejected (non-fast-forward). Use the terminal (git rebase origin/<branch> or git merge) to reconcile diverged histories, then push again.

"Git host is not allowed" error. Only the hosts listed in Supported Remote Hosts are accepted. Self-hosted instances are not supported.

Git panel shows no files after an agent run. The WebSocket may not yet have delivered the updated status. Wait up to 10 seconds for the next poll cycle, or close and reopen the Files tab to trigger a REST refresh.