Alex Blank
c4be7163d6
- 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
160 lines
5.1 KiB
Markdown
160 lines
5.1 KiB
Markdown
# 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.
|