ESPHome YAML history backup

Since ESPHome Device Builder 2026.6, every save under /config/esphome becomes a local git commit. That history lives on the Home Assistant machine. This workflow installs a small app that pushes those commits to a private GitHub repository about 15 seconds after a save in the Builder, encrypts secrets.yaml before it leaves the machine, and can clone the history back onto a fresh, empty ESPHome folder.

Wi-Fi passwords, API keys, and the encryption password for secrets.yaml stay out of the published page. The repository stays private, because device YAML often has API encryption keys written inline.

What problem it solves

You want yesterday’s YAML, and last month’s YAML, back when the Home Assistant disk dies — including one-off boards that exist only as a config file — without restoring an entire Home Assistant backup to read one device.

How it works

1. Builder history — Device Builder already commits each save. The app does not invent a second history. It pushes the commits that are already there.
2. Fast path — a save in the Builder reaches GitHub in about 15 seconds.
3. Slow path — edits made in the File editor, over a network share, or by dropping a file into packages/ are committed and pushed on an interval you set. The project write-up uses an hour for that sweep.
4. Secrets — secrets.yaml is pushed only as secrets.yaml.gpg (AES-256). The password is an app option. Store it in a password manager. The same password decrypts the file on a restore.
5. Access — the default login is a GitHub App limited to the contents of the one repository you select. You approve a one-time code. The grant renews on its own. An SSH deploy key with write access is the alternative.
6. Restore — on a new machine, with an empty /config/esphome, the app clones the repository, history included, and decrypts secrets.yaml. If the folder already has YAML, the app leaves it alone.
7. Failures — a failed push is retried (the project default is three tries). When every try fails, the app raises a persistent notification and an esphome_git_push_failed event. Optional Companion text goes out once per failure streak. The next successful push clears the notification.

The app only adds commits. It does not rewrite GitHub history.

Hardware notes

• Home Assistant OS or Supervised. The app is a supervisor app. A Core or Container install has no Apps panel for it.
• Device Builder 2026.6 or newer. Older Builder releases have no local git history to push.
• Private empty repository. Create it with no README and no .gitignore, so the first push is a clean history. Keep it private.
• Companion. Optional. Point notify_services at a phone if you want the approval code and the failure text off the Home Assistant box.

Snippet

App options, not a live token. The repository slug and the secrets password are filled in the app Configuration tab:

# ESPHome Git Push — configuration tab (secrets password is a separate option)
repository: USER/REPOSITORY
interval_minutes: 60
push_retries: 3
notify_on_failure: true
notify_services: notify.mobile_app_phone

USER/REPOSITORY is the private repo you created. The secrets password is set in that same tab and stored in a password manager. It never goes in a device YAML file.

Setup outline

1. Create an empty private repository on GitHub.
2. In Home Assistant, open Settings → Apps → App store → ⋮ → Repositories and add https://github.com/willrnsantana/ha-esphome-git-push. Install ESPHome Git Push.
3. Install the project’s GitHub App on that repository only (contents read and write). In the app Configuration tab, set repository to USER/REPOSITORY and set secrets_password.
4. Start the app. A notification shows a one-time code and the approval page. Enter the code and approve. Later starts reuse that grant.
5. Save a device in ESPHome Device Builder. Within about 15 seconds the repository should show a new commit, and secrets.yaml.gpg instead of a plain secrets.yaml.
6. On a replacement machine: install Device Builder and this app, set the same repository and password, approve again, and start the app before creating any device. The empty folder is replaced with the cloned history.

Manual copy, from a computer that has git and gpg, when you want the files without waiting for the app:

git clone https://github.com/USER/REPOSITORY.git esphome
gpg -d -o esphome/secrets.yaml esphome/secrets.yaml.gpg

Troubleshooting

• Nothing is pushed. The repository slug is wrong, the GitHub App was installed on a different repo, or the approval code was never entered. The app log names the auth step that stopped.
• secrets.yaml appears in plain text. Encryption was off or the password option was empty on the first push. Rotate the keys that were in that file, set the password, and let the next commit publish secrets.yaml.gpg.
• Restore did nothing. /config/esphome already contained YAML. The app refuses to overwrite. Move that folder aside so the path is empty, then start the app again.
• Push fails and the phone stays quiet. notify_on_failure is off, or notify_services is not a real notify action. The persistent notification and the esphome_git_push_failed event still fire.
• Cannot decrypt after a crash. The password in the new app config does not match the one used to encrypt. The password manager copy is the one that works.

Credits

Based on the community project ESPHome Git Push and the app repository willrnsantana/ha-esphome-git-push. This write-up is an original setup and restore guide, not a paste of that app.