Skip to main content
WebsiteGitHub last commitGitHub commit activityGitHub IssuesDocker PullsDiscordLocalized

Git and GitHub: A Beginner's Guide for Homelabbers

· 4 min read
BankaiTech
Homelab Enthusiast & Self-Hosting Advocate

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 "your@email.com"

# 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​

# Generate SSH key
ssh-keygen -t ed25519 -C "your@email.com"

# 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!