headquarter/docs/guides/config-profiles-git-mounts.md

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.