ESPHome Git Push: a small app to back up your ESPHome YAML history to GitHub

Share your Projects!
1

Hi everyone,

This is a small, simple project I made to solve a personal need, and I’m sharing it in case it helps someone else.

The problem. Some of my ESPHome devices run custom firmware on hardware that doesn’t really exist anywhere else (one of them went through dozens of YAML versions). Since 2026.6 the ESPHome Device Builder keeps a local git history of /config/esphome, which is great, but that history lives only inside Home Assistant. If the machine dies, the only way to get those YAML files back is restoring a full HA backup, and older versions are simply gone. For one-off firmware, that felt too fragile.

What the app does. It’s a Home Assistant app (add-on) that pushes that existing history to a private GitHub repository:

  • every save in the Device Builder reaches GitHub in about 15 seconds; changes made outside the Builder are picked up every hour;
  • secrets.yaml only goes up encrypted (secrets.yaml.gpg, AES256, with a password you choose);
  • on a fresh, empty install it restores everything back, with the full history, and decrypts the secrets;
  • access is approved once with a code (a small GitHub App that can only read and write the contents of the repository you pick), so there’s no key or token to keep;
  • failed pushes are retried, and you can choose to get a notice on your phone or PC.

It never rewrites history and never force-pushes.

Links

It’s tested on my own setup (HA OS, amd64), including a real restore, but that is about it, so please treat it as a young project. If you try it, testing on other setups and suggestions for improvements are very welcome, here or as GitHub issues. And if there’s already a better way to do this that I missed, I’d be happy to learn about it.

Thanks!

2 Likes