docs: add config profile git mounts documentation

- API documentation for config profiles with git mounts endpoint details - User guide for using git repositories in config profiles - Document branch pinning, glob patterns, error handling, and best practices - Update API README to link to new config-profiles documentation
2026-05-26 22:54:59 +02:00
parent 13f55fff47
commit c4be7163d6
4 changed files with 328 additions and 3 deletions
@@ -0,0 +1,159 @@
+# Using Git Repositories in Config Profiles
+
+## Overview
+
+Config profiles now support mounting files and directories from git repositories directly into your tool instances. This is useful for:
+
+- Sharing configuration files across multiple instances
+- Mounting dotfiles or development environment configs
+- Including shared code or assets from other repositories
+- Pinning specific branches or versions of dependencies
+
+## How It Works
+
+When you start a tool instance with a config profile that has git mounts:
+
+1. The system checks if the repository is cloned locally
+2. If not cloned and a remote URL is available, it automatically clones the repository
+3. If a branch is specified, it checks out that branch
+4. Files matching the source path pattern are mounted as bind mounts into the container
+5. Instance startup continues normally
+
+## Adding Git Mounts
+
+### Step 1: Select a Repository
+
+In the config profile editor, find the "Git Mounts" section. Choose a repository from the dropdown. Only repositories from your projects are available.
+
+### Step 2: Configure Source Path
+
+The source path determines which files from the repository to mount:
+
+- **`.`** (default): Mount the entire repository
+- **`configs/`**: Mount the configs directory
+- **`*.json`**: Mount all JSON files in the repository root
+- **`src/**/*.py`**: Mount all Python files in the src directory recursively
+
+**Glob patterns are supported** - use `*` for any characters, `**` for recursive matching.
+
+### Step 3: Set Target Path
+
+The target path is where files appear inside the container:
+
+- `/app/config` - Mount to /app/config
+- `/home/user/dotfiles` - Mount to user's home directory
+- `/workspace/shared` - Mount to workspace shared folder
+
+Target paths must be absolute (start with `/`).
+
+### Step 4: Optional Branch Selection
+
+You can pin a specific branch or tag:
+
+- `main` - Use the main branch
+- `develop` - Use the develop branch
+- `v1.2.3` - Pin to a specific tag
+
+If not specified, the current checked-out branch is used.
+
+## Examples
+
+### Dotfiles Configuration
+
+Mount your dotfiles repository into the home directory:
+
+```
+Repository: dotfiles
+Source Path: .
+Target Path: /home/user
+Branch: main
+```
+
+### Shared Configuration Files
+
+Mount only JSON config files from a shared config repo:
+
+```
+Repository: shared-configs
+Source Path: *.json
+Target Path: /app/config
+Branch: production
+```
+
+### Development Tools Configuration
+
+Mount specific tool configs:
+
+```
+Repository: dev-tools
+Source Path: vscode/
+Target Path: /workspace/.vscode
+```
+
+### Multiple Mounts
+
+You can add multiple git mounts to a single profile:
+
+1. Dotfiles → `/home/user`
+2. Shared configs → `/app/config`
+3. Assets → `/app/static`
+
+## Profile Includes
+
+Git mounts work with profile includes. If Profile A includes Profile B:
+
+- Both profiles' git mounts are merged
+- Same repository + target path combinations override (later profile wins)
+- Different combinations are kept
+
+Example:
+```
+Base Profile:
+  - repo: dotfiles, target: /home/user, branch: main
+
+Development Profile (includes Base):
+  - repo: dotfiles, target: /home/user, branch: develop
+  - repo: dev-tools, target: /opt/tools
+
+Resolved Result:
+  - repo: dotfiles, target: /home/user, branch: develop  (overridden)
+  - repo: dev-tools, target: /opt/tools                   (added)
+```
+
+## Error Handling
+
+Git mounts are non-blocking:
+
+- **Repository not found**: Mount is skipped, instance continues starting
+- **Clone fails**: Mount is skipped, warning logged
+- **Branch doesn't exist**: Falls back to current branch, warning logged
+- **Glob pattern matches nothing**: Mount is skipped, warning logged
+- **Path outside repository**: Match is skipped, warning logged
+
+You can check the instance logs to see which mounts succeeded and which failed.
+
+## Best Practices
+
+1. **Use specific paths**: Instead of mounting the entire repository, mount only the files you need. This reduces startup time and avoids conflicts.
+
+2. **Pin branches**: For reproducible environments, pin specific branches or tags rather than using the default branch.
+
+3. **Keep repositories small**: Large repositories take longer to clone. Consider splitting config repositories from code repositories.
+
+4. **Use absolute target paths**: Always use absolute paths (starting with `/`) for target paths to ensure files end up in the expected location.
+
+5. **Test includes**: When using profile includes, use the Preview feature to verify that git mounts are merged as expected.
+
+## Troubleshooting
+
+**Issue**: Git mount not appearing in container
+**Solution**: Check instance logs for warnings. Common causes: repository not found, clone failure, or source path not matching any files.
+
+**Issue**: Wrong branch mounted
+**Solution**: Verify branch name is correct. If branch doesn't exist locally, the system falls back to the current branch. Ensure the remote has the branch.
+
+**Issue**: Too many files matched
+**Solution**: Use more specific glob patterns. The system limits matches to 100 files per glob pattern.
+
+**Issue**: Permission denied
+**Solution**: Ensure the target path inside the container is writable. Some paths like `/usr` or `/etc` may require root access.