# Git Submodule Workflow

This repository uses git submodules to separate concerns and follow CLAUDE.md guidelines.

## Repository Structure

```
infra-automation/        # Main repository (PUBLIC)
├── inventories/         # → ansible-inventories submodule (PUBLIC)
├── secrets/             # → secrets submodule (PRIVATE)
├── playbooks/
├── roles/
└── docs/
```

## Submodules

### 1. inventories (PRIVATE)
- **URL:** `ssh://git@git.mymx.me:2222/ansible/ansible-inventories.git`
- **Type:** PRIVATE repository
- **Contents:** Dynamic inventories, host/group variables (may contain internal IPs/hostnames)
- **Purpose:** Separate inventory management from infrastructure code, protect internal network topology

### 2. secrets (PRIVATE)
- **URL:** `ssh://git@git.mymx.me:2222/ansible/secrets.git`
- **Type:** PRIVATE repository
- **Contents:** SSH keys, vault files, sensitive data
- **Purpose:** Security isolation, separate access control

## Initial Clone

### Option 1: Clone with submodules (recommended)

```bash
git clone --recurse-submodules ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation
```

### Option 2: Clone then initialize submodules

```bash
git clone ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation
git submodule init
git submodule update
```

## Working with Submodules

### Update All Submodules

```bash
# Update to latest commits from remote
git submodule update --remote

# Commit submodule updates in main repository
git add inventories secrets
git commit -m "Update submodule references"
git push
```

### Update Specific Submodule

```bash
# Update only inventories
git submodule update --remote inventories

# Update only secrets
git submodule update --remote secrets
```

### Making Changes in Submodules

#### Method 1: Work inside submodule

```bash
# Navigate to submodule
cd inventories

# Ensure on correct branch
git checkout master

# Make changes
vim production/libvirt.yml

# Commit and push from submodule
git add production/libvirt.yml
git commit -m "Update libvirt inventory configuration"
git push origin master

# Update parent repository reference
cd ..
git add inventories
git commit -m "Update inventories submodule"
git push
```

#### Method 2: Direct submodule update

```bash
# Make changes, commit, and push in one workflow
cd inventories
git pull origin master
# Make changes
git add .
git commit -m "Changes"
git push origin master
cd ..
git add inventories
git commit -m "Update inventories"
git push
```

### Checking Submodule Status

```bash
# View submodule status
git submodule status

# View detailed info
git submodule

# Check for uncommitted changes in submodules
git submodule foreach git status
```

## Common Workflows

### Workflow 1: Update Inventory Configuration

```bash
# 1. Navigate to inventories
cd inventories

# 2. Pull latest changes
git pull origin master

# 3. Make changes
vim production/group_vars/all.yml

# 4. Commit and push
git add production/group_vars/all.yml
git commit -m "Update production variables"
git push origin master

# 5. Update parent repository
cd ..
git add inventories
git commit -m "Update inventories submodule reference"
git push origin master
```

### Workflow 2: Add New SSH Key to Secrets

```bash
# 1. Navigate to secrets
cd secrets

# 2. Pull latest (important for private repo)
git pull origin master

# 3. Add new key
ssh-keygen -t ed25519 -f ssh/newkey -C "description"

# 4. Document in README
vim ssh/README.md

# 5. Commit and push
git add ssh/
git commit -m "Add new SSH key: newkey"
git push origin master

# 6. Update parent
cd ..
git add secrets
git commit -m "Update secrets submodule"
git push origin master
```

### Workflow 3: Clone Project on New Machine

```bash
# 1. Clone with submodules
git clone --recurse-submodules ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation

# 2. Verify submodules initialized
git submodule status
# Should show: ebe29b6... inventories (heads/master)
#              8def011... secrets (heads/master)

# 3. Set up SSH agent for git operations
source .ssh-agent-init

# 4. Verify inventory works
ansible-inventory -i inventories/production/libvirt.yml --list

# 5. Ready to use!
```

## Troubleshooting

### Submodule Not Initialized

**Problem:** Submodule directory exists but is empty

```bash
# Solution
git submodule init
git submodule update
```

### Submodule Detached HEAD

**Problem:** Submodule is in detached HEAD state

```bash
# Solution: checkout master branch
cd submodule_name
git checkout master
git pull origin master
cd ..
git add submodule_name
git commit -m "Update submodule to track master"
```

### Submodule Changes Not Showing

**Problem:** Made changes in submodule but parent doesn't show update

```bash
# Solution: Stage submodule in parent
git add submodule_name
git commit -m "Update submodule reference"
```

### Permission Denied on Private Submodule

**Problem:** Cannot clone/update secrets submodule

```bash
# Solution: Ensure SSH key is loaded
source /opt/ansible/.ssh-agent-init
ssh-add -l

# Verify access
ssh -T git@git.mymx.me -p 2222

# Try update again
git submodule update --init
```

### Accidentally Committed Changes to Detached HEAD

**Problem:** Made commits in submodule while in detached HEAD

```bash
# Solution: Create branch from detached commits
cd submodule_name
git branch temp-branch
git checkout master
git merge temp-branch
git push origin master
git branch -d temp-branch
```

## Best Practices

### 1. Always Work on Branches
```bash
cd inventories
git checkout master
# Never work in detached HEAD
```

### 2. Pull Before Push
```bash
cd secrets
git pull origin master
# Make changes
git push origin master
```

### 3. Update Parent After Submodule Changes
```bash
# After pushing submodule changes
cd ..
git add submodule_name
git commit -m "Update submodule"
git push
```

### 4. Regular Submodule Updates
```bash
# Weekly: update all submodules
git submodule update --remote
git add inventories secrets
git commit -m "Update submodules to latest"
git push
```

### 5. Document Submodule Changes
```bash
# Use descriptive commit messages
git commit -m "Update inventories: Add staging environment configuration"
```

## Security Considerations

### Secrets Submodule (PRIVATE)
- ⚠️ Never make secrets repository public
- ⚠️ Verify .gitignore before committing
- ⚠️ Use SSH key authentication only
- ⚠️ Regular access audits
- ⚠️ Rotate keys according to schedule

### Inventories Submodule (PRIVATE)
- ⚠️ Private repository - protects network topology
- ⚠️ Contains internal IPs, hostnames, network structure
- ✅ Use vault references for passwords/secrets
- ✅ Document all group/host variables
- ✅ Controlled team access only

## Advanced Operations

### Reset Submodule to Specific Commit

```bash
cd inventories
git checkout <commit-hash>
cd ..
git add inventories
git commit -m "Pin inventories to specific version"
```

### Remove Submodule

```bash
# 1. Deinitialize
git submodule deinit -f inventories

# 2. Remove from git
git rm -f inventories

# 3. Remove module directory
rm -rf .git/modules/inventories

# 4. Commit
git commit -m "Remove inventories submodule"
```

### Change Submodule URL

```bash
# Update .gitmodules
git config --file=.gitmodules submodule.inventories.url <new-url>

# Sync
git submodule sync
git submodule update --init --recursive

# Commit
git add .gitmodules
git commit -m "Update submodule URL"
```

## Quick Reference

| Action | Command |
|--------|---------|
| Clone with submodules | `git clone --recurse-submodules <url>` |
| Init submodules | `git submodule init` |
| Update submodules | `git submodule update` |
| Update to latest | `git submodule update --remote` |
| Check status | `git submodule status` |
| Foreach command | `git submodule foreach <command>` |
| Work in submodule | `cd submodule && git checkout master` |
| Update parent reference | `git add submodule && git commit` |

## Related Documentation

- [Git SSH Setup](git-ssh-setup.md) - SSH key configuration
- [CLAUDE.md](../CLAUDE.md) - Repository structure guidelines
- [ansible-inventories README](https://git.mymx.me/ansible/ansible-inventories) - Inventory documentation
- [secrets README](https://git.mymx.me/ansible/secrets) - Secrets management (PRIVATE)

## Compliance

This submodule structure follows CLAUDE.md requirements with security enhancements:
- ✅ `./inventories` in PRIVATE repository (protects network topology)
- ✅ `./secrets` in PRIVATE repository (protects sensitive data)
- ✅ Separation of concerns
- ✅ Independent version control
- ✅ Proper access controls
- ✅ Network topology protection

---

**Last Updated:** 2025-11-11
**Workflow Version:** 1.0