alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8231e750d976ff211f4d0ff74be7644f75b42829
headquarter/openspec/changes/config-profile-git-mounts/specs/config-profile-git-mounts/spec.md
T
Alex Blank 8231e750d9 docs: update spec to use remote_url instead of repo_id for git mounts 
- Change git mount schema from repo_id to remote_url
- Update validation rules to check URL format instead of repo existence
- Update cloning scenarios to clone directly from URL
- Update UI scenarios to show URL input instead of repo selector
- Remove references to internal/existing repositories
2026-05-27 14:27:39 +02:00

7.0 KiB
Raw Blame History

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:
    • remote_url: Direct git URL (e.g., "https://github.com/user/repo.git", "git@github.com:user/repo.git")
    • 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 "main")

Scenario: Git mount validation

  • WHEN a profile with git mounts is saved
  • THEN the system validates that:
    • remote_url is a valid git URL (starts with https://, git@, or ssh://)
    • source_path is a relative path (no leading /)
    • target_path is an absolute path (starts with /)
    • target_path does not contain path traversal sequences (..)
    • No database lookup or repository existence check is performed (validation is deferred to clone time)

Scenario: Profile with git mounts is resolved

  • GIVEN a config profile with git mounts
  • WHEN the profile is resolved for instance startup
  • THEN the resolved profile includes the git mounts as configured
  • AND repository cloning happens at instance startup time, not at profile resolution

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 is cloned from remote_url to a temporary location
    • The source path within the cloned repository exists
    • A bind mount is created from clone_path/source_path to container:target_path
  • AND if the clone fails 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 to a persistent storage location on every new container creation. Each instance gets its own fresh clone.

Scenario: Repository cloned on container creation

  • GIVEN a git mount with a remote_url
  • WHEN a new container is created with this profile
  • THEN the system clones the repository from the URL to an instance-specific directory
  • AND the clone proceeds as part of instance startup
  • AND instance startup continues once clone completes

Scenario: Existing clone updated on new container creation

  • GIVEN a repository that was previously cloned for this instance
  • WHEN a new container is created with this profile
  • THEN the system pulls the latest updates from the remote_url
  • AND checks out the specified branch (or default branch if not specified)
  • AND uses the updated clone for the bind mount

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

Scenario: Per-instance isolation

  • GIVEN a git mount referencing a repository
  • WHEN multiple instances are created using the same profile
  • THEN each instance gets its own independent clone
  • AND changes made in one container do not affect other containers

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:
    • Git URL
    • 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:
    • Enter a git URL directly (https://, git@, or ssh://)
    • Specify the source path (with autocomplete or validation)
    • Specify the target path in the container
    • Optionally enter a branch/tag name

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 (will clone on container creation)

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
Reference in New Issue View Git Blame Copy Permalink