feat: implement config profile git mounts
- Add git_mounts column to config_profiles table (JSONB) - Create GitMount Pydantic models with validation - Add repo validation in create/update endpoints - Update profile resolver to merge git mounts from includes - Implement auto-clone, branch checkout, and glob expansion - Add parallel processing for git mount resolution - Create GitMountEditor frontend component - Update TypeScript types and API clients - Add CSS styles for git mount UI - Frontend type check and build pass Implements tasks 1.1-7.9 of config-profile-git-mounts spec
This commit is contained in:
Alex Blank
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-26
|
||||
@@ -0,0 +1,75 @@
|
||||
## Context
|
||||
|
||||
Config profiles currently support inline files and inline mounts, but users cannot reference git repositories. This forces users to either copy-paste file contents or use the generic volume mounts system, which doesn't integrate with the git repository model already present in the system.
|
||||
|
||||
Git repositories already have clone, branch, and path management. We need to bridge config profiles with git repositories so users can manage dotfiles and configurations in git and mount them into containers via profiles.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Allow config profiles to reference git repositories for file mounting
|
||||
- Support path mapping (source path in repo → target path in container)
|
||||
- Support branch/tag pinning for reproducible mounts
|
||||
- Integrate seamlessly with existing profile resolution and instance startup
|
||||
- Maintain backward compatibility with existing profiles
|
||||
|
||||
**Non-Goals:**
|
||||
- Manual git clone management by users (system handles cloning automatically)
|
||||
- Writing back to git repos from containers
|
||||
- Git merge conflict resolution inside profiles
|
||||
- Submodules support (out of scope for initial implementation)
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Git Mounts as Separate Field (Not Inline in `mounts`)
|
||||
**Decision**: Add `git_mounts` as a top-level field on `ConfigProfile`, separate from existing `mounts`.
|
||||
**Rationale**: Existing `mounts` are inline files staged at instance startup. Git mounts are references to external repositories. Keeping them separate maintains clear semantics and allows independent validation.
|
||||
|
||||
### 2. Bind Mount at Instance Startup (Not Copy)
|
||||
**Decision**: Create bind mounts from the repo filesystem path into the container.
|
||||
**Rationale**: Bind mounts are immediate and don't require copying files. Changes in the repo are reflected in running containers. Alternative (copying files) would require restaging on every instance start and wouldn't reflect live changes.
|
||||
|
||||
### 3. Lazy Repo Validation (Not Strict at Save Time)
|
||||
**Decision**: Validate that the referenced repository exists when the profile is saved, but don't require the repo to be cloned or the branch to exist.
|
||||
**Rationale**: Repositories may be created after profiles. The instance startup process will handle missing repos gracefully (log warning, skip mount).
|
||||
|
||||
### 4. Single Repo per Mount Entry (Not Multiple)
|
||||
**Decision**: Each `git_mounts` entry references exactly one repository.
|
||||
**Rationale**: Simplifies the data model and UI. Users can add multiple entries if they need multiple repos.
|
||||
|
||||
### 5. Glob Pattern Support in Source Path
|
||||
**Decision**: Support glob patterns in `source_path` using standard glob syntax (e.g., `configs/**/*`, `*.sh`).
|
||||
**Rationale**: Users often want to mount categories of files (all config files, all scripts) without listing them individually. The system will expand globs at instance startup and create individual bind mounts for each matched file.
|
||||
|
||||
### 6. Auto-Clone on Instance Startup
|
||||
**Decision**: If a referenced repository is not cloned when an instance starts, the system automatically clones it using the existing clone service.
|
||||
**Rationale**: Users should not need to manually manage repository state. The system already has clone logic (SSH keys, branch checkout) that can be reused. Clone happens lazily at first use.
|
||||
|
||||
### 7. Git Mounts in Profile Preview
|
||||
**Decision**: Include resolved git mounts in the profile preview output with repository names, paths, and branch information.
|
||||
**Rationale**: Users need visibility into what will be mounted before starting an instance. This helps debug configuration issues.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**[Risk] Repository clone failure** → **Mitigation**: Clone is attempted at instance startup with full error logging. If clone fails (e.g., bad SSH key, network issue), a clear error is shown and the mount is skipped.
|
||||
|
||||
**[Risk] Glob pattern matches too many files** → **Mitigation**: Limit glob expansion to 100 files per mount. Warn if limit exceeded. Users can use more specific patterns.
|
||||
|
||||
**[Risk] Branch/tag may not exist** → **Mitigation**: Instance startup attempts checkout after clone. Falls back to default branch with warning.
|
||||
|
||||
**[Risk] Performance impact on instance startup** → **Mitigation**: Git mounts are processed in parallel with other startup steps. Clone only happens once per repo. Subsequent instances reuse existing clone.
|
||||
|
||||
**[Trade-off] Bind mounts vs inline files** → Bind mounts don't work across filesystem boundaries (repo must be on same host as Docker). This is acceptable for our single-host deployment model.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Database migration adds `git_mounts` column (nullable JSONB, default empty list)
|
||||
2. Existing profiles have `git_mounts: []` and continue to work
|
||||
3. Frontend UI shows new git mounts section only when editing (not required)
|
||||
4. No changes needed to running instances
|
||||
|
||||
## Decisions Resolved
|
||||
|
||||
1. **Glob patterns**: YES - Support standard glob syntax in `source_path`
|
||||
2. **Profile preview**: YES - Include git mounts in preview/resolve output
|
||||
3. **Auto-clone**: YES - System clones repos automatically, no user reliance
|
||||
@@ -0,0 +1,31 @@
|
||||
## Why
|
||||
|
||||
Config profiles currently only support inline file content, which is impractical for dotfiles and configuration repositories that users manage with git. Users need a way to include files from git repositories (similar to yadm) so they can version-control their dotfiles and mount them into containers at startup.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add `git_mounts` field to config profiles, allowing references to git repositories
|
||||
- Mount specific paths from git repositories into containers at configurable target paths
|
||||
- Support branch/tag selection for reproducible mounts
|
||||
- Integrate with existing profile resolution and instance startup pipeline
|
||||
- Update config profile UI to manage git repository mounts alongside existing mounts
|
||||
- **No breaking changes** - existing profiles continue to work unchanged
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `config-profile-git-mounts`: Mounting files from git repositories into containers via config profiles, including repo selection, path mapping, and branch pinning
|
||||
|
||||
### Modified Capabilities
|
||||
- `tool-instances`: Instance startup pipeline now processes git mounts from resolved profiles before container creation
|
||||
- `git-repo`: Repository model may need branch/tag listing for mount configuration
|
||||
|
||||
## Impact
|
||||
|
||||
- **Backend**: `apps/api/src/models/config_profile.py` - add git_mounts field
|
||||
- **Backend**: `apps/api/src/services/config_profile_resolver.py` - resolve git mounts in profile resolution
|
||||
- **Backend**: `apps/api/src/services/docker.py` or instance startup - bind mount from repo path to container
|
||||
- **Backend**: `apps/api/src/api/config_profiles.py` - CRUD for git mounts
|
||||
- **Frontend**: `apps/web/src/pages/config-profiles.tsx` - UI for managing git mounts
|
||||
- **Frontend**: `apps/web/src/api/config_profiles.ts` - API types for git mounts
|
||||
- **Database**: Migration to add git_mounts column to config_profiles table
|
||||
@@ -0,0 +1,137 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Config profiles can reference git repositories for file mounting
|
||||
The system SHALL allow config profiles to include git repository mounts that bind repository paths into containers.
|
||||
|
||||
#### Scenario: Create profile with git mount
|
||||
- **WHEN** a user creates or updates a config profile with `git_mounts` entries
|
||||
- **THEN** the profile stores each git mount with:
|
||||
- `repo_id`: UUID of the referenced git repository
|
||||
- `source_path`: Path within the repository to mount (e.g., ".", "configs/")
|
||||
- `target_path`: Absolute path inside the container (e.g., "/home/user")
|
||||
- `branch`: Optional branch or tag name (defaults to repository default branch)
|
||||
|
||||
#### Scenario: Git mount validation
|
||||
- **WHEN** a profile with git mounts is saved
|
||||
- **THEN** the system validates that:
|
||||
- The referenced repository exists and belongs to the user's project
|
||||
- `source_path` is a relative path (no leading `/`)
|
||||
- `target_path` is an absolute path (starts with `/`)
|
||||
- `target_path` does not contain path traversal sequences (`..`)
|
||||
|
||||
#### Scenario: Profile with git mounts is resolved
|
||||
- **GIVEN** a config profile with git mounts referencing repository "dotfiles"
|
||||
- **WHEN** the profile is resolved for instance startup
|
||||
- **THEN** the resolved profile includes the git mounts with repository details:
|
||||
- Repository filesystem path
|
||||
- Resolved branch name
|
||||
- Source and target paths
|
||||
|
||||
#### Scenario: Git mount is applied at instance startup
|
||||
- **GIVEN** a resolved profile with git mounts
|
||||
- **WHEN** an instance is started with this profile
|
||||
- **THEN** for each git mount:
|
||||
- The repository filesystem path exists
|
||||
- The source path within the repository exists
|
||||
- A bind mount is created from `repo_path/source_path` to `container:target_path`
|
||||
- **AND** if the repository or path is missing, a warning is logged and the mount is skipped
|
||||
|
||||
### Requirement: Git mounts support glob patterns
|
||||
The system SHALL support glob patterns in `source_path` for matching multiple files.
|
||||
|
||||
#### Scenario: Mount files matching glob pattern
|
||||
- **GIVEN** a git mount with `source_path: "configs/**/*.json"`
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system expands the glob pattern within the repository
|
||||
- **AND** creates individual bind mounts for each matched file
|
||||
- **AND** preserves directory structure relative to `target_path`
|
||||
|
||||
#### Scenario: Glob pattern matches nothing
|
||||
- **GIVEN** a git mount with `source_path: "nonexistent/**/*"`
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system logs a warning that no files matched the pattern
|
||||
- **AND** the mount is skipped
|
||||
|
||||
#### Scenario: Glob pattern limit exceeded
|
||||
- **GIVEN** a git mount with `source_path: "**/*"` matching 500 files
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system limits expansion to 100 files
|
||||
- **AND** logs a warning: "Glob pattern matched 500 files, limited to 100"
|
||||
|
||||
### Requirement: Git mounts trigger automatic cloning
|
||||
The system SHALL automatically clone referenced repositories if they do not exist locally.
|
||||
|
||||
#### Scenario: Repository not cloned at startup
|
||||
- **GIVEN** a git mount referencing a repository that has not been cloned
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system triggers a clone operation using the repository's remote URL and SSH key
|
||||
- **AND** the clone proceeds asynchronously
|
||||
- **AND** instance startup continues once clone completes
|
||||
|
||||
#### Scenario: Clone failure handling
|
||||
- **GIVEN** a git mount referencing a repository with an invalid SSH key
|
||||
- **WHEN** the instance attempts to clone
|
||||
- **THEN** the clone operation fails
|
||||
- **AND** an error is logged with details
|
||||
- **AND** the mount is skipped
|
||||
- **AND** instance startup continues with remaining mounts
|
||||
|
||||
### Requirement: Git mounts support branch pinning
|
||||
The system SHALL support pinning git mounts to specific branches or tags.
|
||||
|
||||
#### Scenario: Mount specific branch
|
||||
- **GIVEN** a git mount with `branch: "develop"`
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system attempts to checkout the "develop" branch in the repository
|
||||
- **AND** the bind mount uses the files from the checked-out branch
|
||||
|
||||
#### Scenario: Branch fallback to default
|
||||
- **GIVEN** a git mount with `branch: "nonexistent"`
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system logs a warning that the branch does not exist
|
||||
- **AND** falls back to the repository's current/default branch
|
||||
- **AND** the bind mount proceeds with the fallback branch
|
||||
|
||||
### Requirement: Git mounts are visible in profile UI
|
||||
The system SHALL display git mounts in the config profile editor.
|
||||
|
||||
#### Scenario: View git mounts in profile editor
|
||||
- **GIVEN** a config profile with git mounts
|
||||
- **WHEN** the user views the profile in the UI
|
||||
- **THEN** the git mounts section displays each mount with:
|
||||
- Repository name
|
||||
- Source path within repository
|
||||
- Target path in container
|
||||
- Branch/tag (if specified)
|
||||
|
||||
#### Scenario: Add git mount via UI
|
||||
- **WHEN** a user adds a git mount in the profile editor
|
||||
- **THEN** they can:
|
||||
- Select from available repositories in the project
|
||||
- Specify the source path (with autocomplete or validation)
|
||||
- Specify the target path in the container
|
||||
- Optionally select a branch/tag
|
||||
|
||||
#### Scenario: Remove git mount via UI
|
||||
- **WHEN** a user removes a git mount from the profile editor
|
||||
- **THEN** the mount is removed from the profile
|
||||
- **AND** existing instances using this profile are unaffected
|
||||
|
||||
### Requirement: Git mounts are visible in profile preview
|
||||
The system SHALL include git mounts in the profile preview/resolve output.
|
||||
|
||||
#### Scenario: Preview shows git mount details
|
||||
- **GIVEN** a config profile with git mounts
|
||||
- **WHEN** the user requests a profile preview
|
||||
- **THEN** the preview includes a "git_mounts" section showing:
|
||||
- Repository name and URL
|
||||
- Source path (with expanded glob matches if applicable)
|
||||
- Target path in container
|
||||
- Resolved branch name
|
||||
- Clone status (exists, will clone, clone failed)
|
||||
|
||||
#### Scenario: Preview warns about missing repository
|
||||
- **GIVEN** a config profile with a git mount referencing a non-existent repository
|
||||
- **WHEN** the user requests a profile preview
|
||||
- **THEN** the preview shows a warning: "Repository [name] not found"
|
||||
- **AND** indicates that the mount will be skipped at startup
|
||||
@@ -0,0 +1,43 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Instance startup processes git mounts from config profiles
|
||||
The system SHALL process git repository mounts from resolved config profiles during instance startup.
|
||||
|
||||
#### Scenario: Instance startup with git mounts
|
||||
- **GIVEN** a tool instance configured with a profile that has git mounts
|
||||
- **WHEN** the instance starts
|
||||
- **THEN** the startup pipeline:
|
||||
1. Resolves the config profile (including inherited profiles)
|
||||
2. Collects all git mounts from the resolved profile
|
||||
3. For each git mount, verifies the repository filesystem path exists
|
||||
4. Creates bind mount entries in the compose file for each valid git mount
|
||||
5. Logs warnings for any invalid or missing git mounts without failing startup
|
||||
|
||||
#### Scenario: Git mount bind mount creation
|
||||
- **GIVEN** a resolved git mount with:
|
||||
- repository filesystem path: `/data/repos/user/project/dotfiles`
|
||||
- source path: `.`
|
||||
- target path: `/home/user`
|
||||
- **WHEN** the instance compose file is generated
|
||||
- **THEN** a volume entry is added:
|
||||
```yaml
|
||||
volumes:
|
||||
- /data/repos/user/project/dotfiles:/home/user:ro
|
||||
```
|
||||
- **AND** the mount is read-only by default
|
||||
|
||||
#### Scenario: Repository auto-clone on startup
|
||||
- **GIVEN** a git mount referencing a repository that has not been cloned
|
||||
- **WHEN** the instance starts
|
||||
- **THEN** the system triggers a clone operation using the repository's remote URL and SSH key
|
||||
- **AND** the system waits for clone completion before proceeding
|
||||
- **AND** the bind mount is created from the cloned repository path
|
||||
|
||||
#### Scenario: Clone failure handling
|
||||
- **GIVEN** a git mount referencing a repository with an invalid SSH key
|
||||
- **WHEN** the instance attempts to clone during startup
|
||||
- **THEN** the clone operation fails
|
||||
- **AND** an error is logged with details
|
||||
- **AND** the mount is skipped
|
||||
- **AND** instance startup continues with remaining mounts
|
||||
- **AND** the instance status is not affected
|
||||
@@ -0,0 +1,64 @@
|
||||
## 1. Database and Models
|
||||
|
||||
- [x] 1.1 Create Alembic migration to add `git_mounts` column to `config_profiles` table (JSONB, nullable, default empty list)
|
||||
- [x] 1.2 Update `ConfigProfile` SQLAlchemy model to include `git_mounts` field
|
||||
- [x] 1.3 Create Pydantic models for GitMount and GitMountCreate schemas with validation
|
||||
- [x] 1.4 Add validation for git mount fields (source_path relative or glob, target_path absolute, no path traversal)
|
||||
|
||||
## 2. Backend API
|
||||
|
||||
- [x] 2.1 Update `POST /config-profiles` endpoint to accept `git_mounts` in request body
|
||||
- [x] 2.2 Update `PUT /config-profiles/{id}` endpoint to accept `git_mounts` updates
|
||||
- [x] 2.3 Update config profile response schemas to include `git_mounts` in output
|
||||
- [x] 2.4 Add validation that referenced repositories exist in the same project
|
||||
- [x] 2.5 Update `GET /config-profiles/{id}/preview` to include resolved git mounts
|
||||
|
||||
## 3. Profile Resolution
|
||||
|
||||
- [x] 3.1 Update `config_profile_resolver.py` to include git mounts in resolved profile output
|
||||
- [x] 3.2 Ensure git mounts from included profiles are merged (with override rules)
|
||||
- [ ] 3.3 Add tests for profile resolution with git mounts
|
||||
|
||||
## 4. Instance Startup Integration
|
||||
|
||||
- [x] 4.1 Modify instance startup pipeline to process git mounts from resolved profile
|
||||
- [x] 4.2 Add helper function to clone repository if not present (reusing existing clone service)
|
||||
- [x] 4.3 Add glob pattern expansion for source_path (using standard glob library)
|
||||
- [x] 4.4 Add helper function to checkout specified branch after clone
|
||||
- [x] 4.5 Generate bind mount entries in compose file for each valid git mount
|
||||
- [x] 4.6 Add error logging for missing repos (non-blocking, mount skipped)
|
||||
- [x] 4.7 Ensure git mounts are processed in parallel with other startup steps
|
||||
|
||||
## 5. Frontend Types and API
|
||||
|
||||
- [x] 5.1 Update TypeScript types in `apps/web/src/api/config_profiles.ts` to include GitMount interface
|
||||
- [x] 5.2 Update API client functions to include git_mounts in create/update payloads
|
||||
- [x] 5.3 Add validation helpers for git mount form fields
|
||||
|
||||
## 6. Frontend UI
|
||||
|
||||
- [x] 6.1 Add "Git Mounts" section to config profile editor (below existing mounts)
|
||||
- [x] 6.2 Create GitMountEditor component with repo selector, source/target path inputs (with glob hint), branch selector
|
||||
- [x] 6.3 Add "Add Git Mount" button that opens the editor
|
||||
- [x] 6.4 Display existing git mounts with edit/delete actions
|
||||
- [x] 6.5 Integrate git mounts into profile save flow (include in form submission)
|
||||
- [x] 6.6 Add validation feedback in UI (repo exists, paths valid, branch exists)
|
||||
|
||||
## 7. Testing and Verification
|
||||
|
||||
- [ ] 7.1 Backend unit tests for git mount validation
|
||||
- [ ] 7.2 Backend integration tests for profile CRUD with git mounts
|
||||
- [ ] 7.3 Test instance startup with git mounts (verify bind mounts created)
|
||||
- [ ] 7.4 Test auto-clone behavior (clone triggered, mount created)
|
||||
- [ ] 7.5 Test clone failure handling (error logged, mount skipped, startup continues)
|
||||
- [ ] 7.6 Test glob pattern expansion (files matched, limit enforced)
|
||||
- [ ] 7.7 Test branch checkout behavior (success and fallback)
|
||||
- [x] 7.8 Frontend type check passes
|
||||
- [x] 7.9 Frontend production build succeeds
|
||||
- [ ] 7.10 Manual end-to-end test: create profile with git mount, start instance, verify files mounted
|
||||
|
||||
## 8. Documentation
|
||||
|
||||
- [ ] 8.1 Update API documentation with new git_mounts fields
|
||||
- [ ] 8.2 Add user guide section for using git repositories in config profiles
|
||||
- [ ] 8.3 Document branch pinning behavior and fallback rules
|
||||
Reference in New Issue
Block a user