infra-automation/docs/submodule-workflow.md

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)

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

Option 2: Clone then initialize submodules

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Solution
git submodule init
git submodule update

Submodule Detached HEAD

Problem: Submodule is in detached HEAD state

# 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

# 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

# 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

# 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

cd inventories
git checkout master
# Never work in detached HEAD

2. Pull Before Push

cd secrets
git pull origin master
# Make changes
git push origin master

3. Update Parent After Submodule Changes

# After pushing submodule changes
cd ..
git add submodule_name
git commit -m "Update submodule"
git push

4. Regular Submodule Updates

# 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

# 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

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

Remove Submodule

# 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

# 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 - SSH key configuration
• CLAUDE.md - Repository structure guidelines
• ansible-inventories README - Inventory documentation
• secrets README - 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