Git-push-to-deploy for your homelab: stop SSHing in to change things
TL;DR: Put every Docker Compose stack in a git repo, make a push to
mainthe only way a change reaches the server, and treat any hand-edit on the box as a bug. You get history, rollback and a written record of your setup for free. The tooling barely matters; the rule does.
Most homelabs start the same way. You SSH in, cd somewhere, edit a
docker-compose.yml in nano, run docker compose up -d, and it works. Then you
do it again for the next service, and the next. Six months later something breaks
and you’re trying to remember which of the forty edits you made in March mattered.
I ran mine like that for longer than I’d like to admit. The fix wasn’t a fancy tool. It was one rule: the server only ever runs what’s in the repo, and the repo only changes by a commit.
Why “just SSH in” stops working
SSHing in and editing live is fast, and that’s exactly the problem. It’s fast in the moment and slow every time after:
- There’s no history. When a container starts misbehaving, you can’t ask “what changed?” because nothing recorded the change.
- There’s no rollback. Undoing a bad edit means remembering what the file said before, and you won’t.
- There’s no second copy. If the disk dies, your configuration dies with it. Backing up the data is one thing; rebuilding forty services from memory is another.
- It drifts. The file on disk, the file you think is on disk, and the container that’s actually running slowly become three different things.
None of this hurts on day one. All of it hurts on day three hundred.
What push-to-deploy actually means
The shape is simple:
- One git repo (or one per stack, if you prefer) holds every
compose.yml, config file and the non-secret parts of each service’s environment. - You edit on your laptop, commit, and push.
- Something on the server notices the push and brings the running stack in line with the repo.
That “something” can be a lot of things. A container-management UI that can deploy a
stack from a git repository and redeploy when it changes. A small webhook listener
that runs git pull && docker compose up -d. A systemd timer that does the same
every few minutes. A full GitOps controller if you’re on Kubernetes. I’ve used the
UI approach and the dumb-script approach, and I’d honestly be happy with either.
The tool is the least important decision here. Pick whatever you’ll actually keep running. The discipline is what does the work.
The rule that makes it work
The whole thing collapses the moment you “just quickly” fix something on the box. So the rule has to be absolute: a hand-edit on the server is a bug. If you had to change something live during an outage, fine, but the very next thing you do is commit that change to the repo, or the next deploy will silently undo your fix. Unpinned image tags are the other way a deploy changes what runs without a commit; see pin your Docker image tags.
Once you hold that line, a few nice properties fall out:
git logis your change history. Every change has a date and a message explaining why.git revertis your rollback. Bad upgrade? Revert the commit, push, done.- The repo is your documentation. A new machine, or a future you who has forgotten everything, can read exactly how each service is set up.
- Rebuilding is boring. New disk, fresh OS, point the deploy tool at the repo.
Secrets do not go in the repo
This is the one place people get burned. Your compose files belong in git; your passwords, API tokens and private keys do not, even in a private repo. Private repos get made public by accident, get cloned onto laptops, and get pushed to the wrong remote.
Keep secrets out of band: in the deploy tool’s own environment settings, in an
.env file on the server that’s listed in .gitignore, or in a proper secrets
manager if you have one. Commit an .env.example with the variable names and
placeholder values so the repo still documents what each stack needs.
Make “did my push land?” answerable
The quiet failure mode of push-to-deploy is a push that didn’t deploy. The webhook didn’t fire, the pull failed, the container didn’t restart, and you’re debugging a change that isn’t actually running.
Give yourself a cheap way to check. For a website, serve a tiny build-info endpoint
with the commit it was built from. For other services, a label or environment
variable with the commit hash that you can see in docker inspect works. The point
is that “is my change live?” should take one command, not a guessing game.
Start small
You don’t have to migrate everything this weekend. Pick the one stack you touch most
often, move its files into a repo, wire up the deploy, and live with it for a couple of
weeks. Once you’ve rolled back a bad change with a single git revert, you’ll move the
rest yourself.
The best homelab is the one you can rebuild without remembering anything. Git gets you most of the way there.