headquarter/openspec/changes/archive/2026-05-22-repo-clone-mode-with-ssh/proposal.md at b7396d58d2d400a6d7cf22dc863c8efb6ef6b518

Files

T

Fusion 063a839790 feat: implement repository clone mode with SSH key support

- Add clone_mode and branch fields to tool_instances
- Add ssh_key_id to git_repositories for per-repo SSH key assignment
- Implement host-side git cloning with branch selection (default: main)
- Mount SSH keys into containers for git operations in clone mode
- Add dirty state check on clone-mode instance deletion with confirmation
- Update SessionsPage with mount/clone selector, branch input, SSH key display
- Add SSH key selector to repository creation form
- Add dirty delete confirmation modal with changed files list
- Update API schemas and endpoints for new fields
- Sync delta specs to main specs (git-repo, tool-instances, repo-clone-mode)
- Archive completed OpenSpec change: repo-clone-mode-with-ssh
- Document git requirement for custom tool types

Quality gates: Frontend typecheck and build passed
OpenSpec: repo-clone-mode-with-ssh archived with all tasks complete

2026-05-22 22:56:35 +02:00

2.7 KiB

Raw Blame History

Why

Currently all tool instances bind-mount the host repository directory, giving containers live access to the working copy. Users need the ability to launch instances with an isolated fresh clone instead — useful for experimentation, clean-room development, or running tools that modify files without affecting the host copy. Additionally, containers need SSH key access to perform git operations (push/pull) inside the clone.

What Changes

Repository-level SSH key assignment: Each GitRepository can be associated with an SSH key (used for cloning and container git access). Configurable at creation time and editable later.
Clone mode for tool instances: When creating a tool instance, users can choose between:
- Mount (default): Bind-mount the host repository directory (current behavior)
- Clone: Clone the repository into the instance directory with full history
Branch selection: When clone mode is selected, users can specify a branch (defaults to main).
SSH key mounting: The repository's SSH key is decrypted and mounted into the container's ~/.ssh/ directory, enabling git operations inside the container.
Dirty check on delete: When deleting a clone-mode instance, check for uncommitted changes in the cloned repository. If changes exist, warn the user and require confirmation before deletion.
Frontend UI updates: Sessions page gets a repository access mode selector (mount/clone), branch input, and SSH key selector when clone is chosen.
Backend API updates: POST /instances accepts clone_mode and branch; new endpoint for updating repository SSH key.
Database migrations: Add ssh_key_id to git_repositories, clone_mode and branch to tool_instances.

Capabilities

New Capabilities

repo-clone-mode: Repository clone mode with host-side cloning, branch selection, and SSH key mounting for container git access.

Modified Capabilities

git-repo: Add ssh_key_id field and API for associating SSH keys with repositories.
tool-instances: Extend instance creation to support clone_mode and branch, mount SSH keys at startup, and perform dirty check on deletion.

Impact

Database: Migrations for git_repositories.ssh_key_id, tool_instances.clone_mode, tool_instances.branch
Backend API: POST /instances schema change, new PATCH /repositories/{id}/ssh-key endpoint, instance delete logic update
Frontend: SessionsPage form additions, confirmation modal for dirty delete
Docker: Dynamic SSH key volume injection via _modify_compose_file
Tool types: Built-in tool images assumed to have git installed (code-server, jupyter do; opencode template already installs git)

2.7 KiB Raw Blame History

Why