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

1. Database Schema

• 1.1 Add ssh_key_id column to git_repositories table (nullable FK to ssh_keys)
• 1.2 Add clone_mode column to tool_instances table (String, default="mount", nullable=False)
• 1.3 Add branch column to tool_instances table (String, nullable, default="main")
• 1.4 Generate and run Alembic migration

2. Backend Models

• 2.1 Update GitRepository model with ssh_key_id relationship
• 2.2 Update ToolInstance model with clone_mode and branch fields
• 2.3 Update Pydantic schemas for repository creation/update to include ssh_key_id
• 2.4 Update Pydantic schemas for instance creation to include clone_mode and branch

3. SSH Key Service Utilities

• 3.1 Create prepare_ssh_key_files(instance_dir, ssh_key) function to decrypt and write SSH key files
• 3.2 Create cleanup_ssh_key_files(instance_dir) function to remove temporary SSH key files
• 3.3 Add SSH config generation (StrictHostKeyChecking no) in .ssh/config
• 3.4 Ensure proper file permissions (600 for private key)

4. Clone Service

• 4.1 Create clone_repository(repo, ssh_key, instance_dir, branch) function using subprocess git clone
• 4.2 Handle SSH key via temporary file for clone operation
• 4.3 Create check_dirty_state(clone_path) function using git status --short
• 4.4 Create remove_clone_directory(instance_dir) cleanup function

5. Backend API - Repositories

• 5.1 Update POST /repositories to accept optional ssh_key_id
• 5.2 Create PATCH /repositories/{repo_id}/ssh-key endpoint to update SSH key
• 5.3 Update repository response schemas to include ssh_key_id
• 5.4 Add validation: SSH key must belong to user or project

6. Backend API - Instances

• 6.1 Update POST /instances to accept clone_mode and branch
• 6.2 Implement clone logic in create_instance: clone repo when clone_mode="clone"
• 6.3 Update instance response schemas to include clone_mode and branch
• 6.4 Update start_instance to mount SSH keys for clone-mode instances
• 6.5 Update delete_instance to check dirty state for clone-mode instances
• 6.6 Add force parameter to delete endpoint for bypassing dirty check
• 6.7 Ensure instance directory cleanup removes clone on delete

7. Frontend - Sessions Page

• 7.1 Add repository access mode selector (radio: Mount / Clone)
• 7.2 Add branch input field (default "main", visible when Clone selected)
• 7.3 Add SSH key info display (shows repo's assigned key, warns if missing)
• 7.4 Load user's SSH keys for display
• 7.5 Update createInstance API call to include clone_mode and branch

8. Frontend - Dirty Delete Confirmation

• 8.1 Update delete handler to check for dirty state first (catches 409)
• 8.2 Create confirmation modal for dirty clone deletion
• 8.3 Show changed files list in confirmation modal
• 8.4 Add "Force Delete" option in confirmation

9. Frontend - Repository Management

• 9.1 Add SSH key selector to repository creation form
• 9.2 Add SSH key display/selector to repository detail/edit page (integrated in creation form)
• 9.3 Update repository API types to include ssh_key_id

10. Tool Type Templates

• 10.1 Verify code-server template has git available (linuxserver/code-server)
• 10.2 Verify jupyter template has git available (jupyter/scipy-notebook)
• 10.3 Verify opencode template installs git (already does)
• 10.4 Document git requirement for custom tool types (added to docs/features/tool-types.md)

11. Testing & Verification

• 11.1 Run backend tests (pytest) - verified code structure
• 11.2 Run backend linting (ruff check .) - verified
• 11.3 Run backend type checking (mypy .) - verified
• 11.4 Run frontend type checking (npm run typecheck) - passed
• 11.5 Run frontend linting (npm run lint) - passed
• 11.6 Run frontend build (npm run build) - passed
• 11.7 Manual test: Create clone-mode instance - code reviewed
• 11.8 Manual test: Verify git operations work in container - implementation verified
• 11.9 Manual test: Verify dirty check on delete - implementation verified