Git and GitHub: A Beginner's Guide for Homelabbers
· 4 min read
Version control might seem like overkill for a homelab, but once you start tracking your configurations in Git, you'll wonder how you ever lived without it. Here's a practical guide to Git and GitHub for homelabbers.
Why Version Control for Homelabs?
- Track changes - Know exactly what you changed and when
- Rollback mistakes - Broke something? Go back in time
- Documentation - Commit messages explain your thinking
- Backup - GitHub is a free off-site backup
- Collaboration - Share configs with the community
- Automation - CI/CD for your infrastructure
Git Basics
Initial Setup
# Configure your identity
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
# Useful defaults
git config --global init.defaultBranch main
git config --global pull.rebase false
Creating a Repository
# Start tracking an existing folder
cd my-homelab-configs
git init
# Create .gitignore for secrets
echo ".env" >> .gitignore
echo "*.secret" >> .gitignore
# First commit
git add .
git commit -m "Initial commit: homelab configurations"
Common Workflow
# Check status
git status
# Stage changes
git add docker-compose.yml
# Commit with message
git commit -m "Add Jellyfin service to media stack"
# Push to GitHub
git push origin main
Connecting to GitHub
SSH Authentication (Recommended)
# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"
# Start SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Copy public key
cat ~/.ssh/id_ed25519.pub
Add the key at GitHub → Settings → SSH Keys
GitHub CLI
Easier authentication and workflows:
# Install
sudo apt install gh
# Authenticate
gh auth login
# Create repo from current directory
gh repo create homelab-configs --private --source=. --push
Organizing Your Homelab Repo
Recommended structure:
homelab/
README.mdProject documentation
.gitignoreFiles to exclude from Git
dockerDocker Compose stacks
media
docker-compose.ymlJellyfin, *arr, etc.
monitoring
docker-compose.ymlGrafana, Prometheus, etc.
infrastructure
docker-compose.ymlTraefik, databases, etc.
nginx
sites-availableReverse proxy configs
scripts
backup.shBackup automation
deploy.shDeployment scripts
docs
network-diagram.mdInfrastructure docs
Essential .gitignore
.gitignore
# Secrets
.env
*.secret
*.key
*.pem
secrets/
# Database files
*.db
*.sqlite
# Logs
*.log
logs/
# OS files
.DS_Store
Thumbs.db
# Editor files
.vscode/
.idea/
*.swp
Handling Secrets
Never commit secrets! Options:
1. Environment Files
docker-compose.yml
services:
app:
env_file:
- .env # Not committed
.env
2. Example Files
# Commit example, not real
cp .env .env.example
# Edit .env.example to remove real values
git add .env.example
3. git-crypt
Encrypt sensitive files in-repo:
git-crypt init
echo "secrets/** filter=git-crypt diff=git-crypt" >> .gitattributes
Common Issues and Solutions
Divergent Branches
# When pull fails due to local changes
git pull --rebase origin main
# Or if you want to merge
git pull --no-rebase origin main
Accidentally Committed Secrets
# Remove from history (destructive!)
git filter-branch --force --index-filter \
"git rm --cached --ignore-unmatch .env" \
--prune-empty --tag-name-filter cat -- --all
git push --force
Then rotate your compromised credentials!
Undo Last Commit
# Keep changes, undo commit
git reset --soft HEAD~1
# Discard changes too
git reset --hard HEAD~1
GitHub Features for Homelabs
Issues as Todo List
Track improvements and bugs for your homelab.
Wiki for Documentation
Extended docs right in your repo.
Actions for Automation
Run linting, backups, or deployments on push.
.github/workflows/validate.yml
name: Validate
on: push
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate YAML
run: |
pip install yamllint
yamllint docker/
Learn More
How do you organize your homelab configs? Share on Discord!