headquarter/openspec/changes/archive/2025-05-18-git-repo-management/design.md

Context

The platform has projects and SSH keys but no git repository management. Users need to create bare repos for their projects and optionally clone external ones.

Goals / Non-Goals

Goals:

• Create bare git repositories on disk within project structure
• List repositories per project
• Clone external repositories as bare mirrors
• Delete repositories (cascade with project deletion)
• Prevent duplicate repo names per project

Non-Goals:

• Git hosting (push/pull via SSH/HTTP)
• Webhook handling
• CI/CD integration
• Repository browsing/file viewing

Decisions

1. Bare repositories only

   • Simplifies storage, no working tree needed
   • Standard pattern for git servers

2. Storage path: /data/repos/{user_id}/{project_id}/{name}.git

   • Isolates repos by user and project
   • Predictable structure

3. Use subprocess to run git init --bare and git clone --mirror

   • Standard git commands, no additional dependencies
   • More reliable than git libraries for basic operations

4. Store only metadata in database

   • Name, path, remote_url, project_id
   • Actual git data stays on disk

Risks / Trade-offs

• [Disk space] -> Monitor usage, implement cleanup
• [Git not in container] -> Ensure git is installed in API Dockerfile
• [Concurrent access] -> File locking not implemented (future)

Migration Plan

1. Create API endpoints
2. Add git to Dockerfile
3. Create frontend
4. Test with sample repos

Open Questions

• Should we validate git URLs before cloning?