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 main the 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:

  1. 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.
  2. You edit on your laptop, commit, and push.
  3. 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 log is your change history. Every change has a date and a message explaining why.
  • git revert is 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.