Mit der HACS-Integration git-ha-ppens von Manu kannst du deine Home Assistant Konfiguration automatisiert per Git versionieren. Die Integration synchronisiert deine Dateien zwischen Home Assistant und einem Remote-Repository und erlaubt es dir, fehlerhafte Änderungen direkt aus der Home Assistant Oberfläche heraus gezielt zurückzurollen – ganz ohne zusätzlichen Container.
Das Problem: Was hast du geändert als es kaputtging?
Kennst du das? Du änderst eine Automation, testest sie und alles läuft perfekt. Zwei Wochen später funktioniert plötzlich etwas nicht mehr wie erwartet, aber du weißt weder genau, was du geändert hast, noch wie der letzte funktionierende Stand aussah.
Für genau dieses Problem habe ich bereits Home Assistant Time Machine vorgestellt – ein starkes Tool mit eigenem Backend für YAML-Backups und Diff-Ansicht, das als Add-on oder Docker-Container läuft. git-ha-ppens verfolgt hingegen einen schlankeren Ansatz: Es nutzt echtes Git, bettet sich komplett in die Home Assistant Oberfläche ein und benötigt keinen separaten Container.
Laut Entwickler Manu ist die Abgrenzung zu bekannten Projekten wie Home Assistant Version Control bewusst gewählt. Während letzteres als vollwertiges Add-on mit großem Funktionsumfang konzipiert ist, versteht sich git-ha-ppens als einfache Integration. Sie bringt eigene Sensoren sowie Services/Aktionen für Automationen, Statistiken und Trigger direkt mit.
Voraussetzungen und Installation
Du benötigst mindestens Home Assistant 2024.1. Die Installation erfolgt über HACS, die Einrichtung klassisch über „Einstellungen“ > „Geräte und Dienste“.
Nutzt du Home Assistant OS, muss Git auf dem System verfügbar sein. Das SSH und Web Terminal Add-on bringt es meist schon mit. Alternativ lässt es sich über die Konsole mit dem Befehl
apk add git
nachinstallieren.
Ein großer Pluspunkt: git-ha-ppens ist nicht auf GitHub limitiert. Auch GitLab, Bitbucket oder jedes andere Git-Remote funktioniert problemlos – wahlweise per HTTPS-Token oder SSH-Schlüssel.
Ein Hinweis zum Offline-Verhalten (dies ist eine Annahme und nicht offiziell bestätigt): Rein architektonisch sollten das lokale Tracking, Committen und auch der Rollback unabhängig von einer Internetverbindung weiterlaufen. Lediglich Fetch, Push und Pull würden bei einer Unterbrechung naturgemäß scheitern. Explizit dokumentiert ist dies jedoch nicht, und ich habe es selbst noch nicht getestet.
Erstes Repository, Personal Access Token und .gitignore
Für den Start benötigst du ein komplett leeres und privates GitHub-Repository. Es darf wirklich nichts enthalten sein – auch keine automatisch generierte README-Datei –, da es sonst beim ersten Push zu Problemen kommt.
Für den Personal Access Token gilt die Regel: Berechtigungen so eng wie möglich fassen. Beschränke den Zugriff auf genau dieses eine Repository, vergib nur die nötigen Rechte und setze ein Ablaufdatum. Nutzt du einen Fine-grained Token, reicht die Berechtigung Contents: Read and write völlig aus.
Die automatisch erstellte .gitignore schließt sensible und dynamische Dateien bereits zuverlässig aus. Dazu gehören beispielsweise die secrets.yaml, der .storage Ordner, Datenbanken und Logs. Auch die state.json und coordinator_backup.json von Zigbee2MQTT sind standardmäßig ausgenommen. Bei Bedarf kannst du die .gitignore direkt in Home Assistant anpassen (unter Einstellungen > Geräte und Dienste > git-ha-ppens > Konfigurieren > .gitignore bearbeiten).
Wichtiger Achtungspunkt: Deine Helfer landen technisch im .storage Ordner. Da dieser standardmäßig komplett ausgeschlossen ist (hier liegen auch Auth-Daten, Zertifikate und Keys), werden Helfer nicht mitversioniert. Wenn du die .gitignore anpasst, um Helfer einzuschließen, riskierst du, unabsichtlich auch diese hochsensiblen Dateien preiszugeben. Dies ist eine bekannte Einschränkung, an deren Lösung laut Manu bereits gearbeitet wird.
Kontrolliere unbedingt vor deinem allerersten Push, ob die .gitignore wirklich alle sensiblen Daten abdeckt – insbesondere bei eigenen Paketen mit Zugangsdaten. Denke an den klassischen Git-Stolperstein: Bereits getrackte Dateien verschwinden nicht automatisch aus der Historie, nur weil du sie nachträglich in die .gitignore einträgst.
Der Alltag: Automatisches Commit und Push
Sobald du eine Automation änderst – egal ob per YAML oder komplett über die UI –, erkennt die Integration das automatisch. Nach Ablauf des konfigurierten Intervalls (Standard: 5 Minuten) wird die Änderung committet und im Anschluss automatisch gepusht.
Auf der Geräteseite findest du dafür eine Reihe hilfreicher Sensoren. Diese zeigen dir beispielsweise uncommittete Änderungen an, den letzten Commit, oder ob dein lokaler Stand dem Remote voraus ist oder hinterherhinkt. Zusätzlich gibt es Buttons für manuelles Fetchen, Pullen und Pushen.
Ein cleveres Sicherheitsfeature arbeitet im Hintergrund: Die Integration scannt getrackte Dateien automatisch auf typische Muster von API-Keys, Tokens oder Passwörtern und meldet Funde, bevor sie hochgeladen werden und zum Problem werden können.
Achtung bei Multi-User-Systemen: Das automatische Push-Verhalten ist primär für Single-User-Setups ausgelegt. Wenn mehrere Personen oder auch KI-Agenten parallel über die UI an der Config arbeiten, kann es bei den automatischen Commits und Pushes zu Konflikten kommen.
Hier findest du meine Vorstellung von git-ha-ppens auch als Video:
GitOps: Bidirektionaler Sync und Pre-Deploy-Check
Der Kern des GitOps-Ansatzes: Die Synchronisation funktioniert in beide Richtungen. Du kannst Änderungen auch remote vornehmen – zum Beispiel direkt auf GitHub – und sie werden automatisch in Home Assistant übernommen. Wie oft das System nach neuen Commits sucht, definiert das Fetch-Intervall (standardmäßig alle 5 Minuten).
Der wichtigste Sicherheitsaspekt der gesamten Integration ist der Pre-Deploy-Check: Nach jedem Pull prüft das System automatisch, ob die neue Home Assistant Konfiguration gültig ist. Schlägt diese Prüfung fehl, wird automatisch auf den letzten funktionierenden Stand zurückgerollt, inklusive Benachrichtigung. Ich habe das mit einer absichtlich fehlerhaften Config getestet und die Instanz blieb absolut stabil.
Fehlerhafte Änderungen zurückrollen
Manchmal besteht eine Änderung zwar die Konfigurationsprüfung, tut aber inhaltlich nicht das, was sie soll. Für solche Fehler gibt es eine eingebaute Rollback-Funktion direkt in der Oberfläche (unter Einstellungen > git-ha-ppens > Konfiguration wiederherstellen). Hier kannst du aus einer Liste der letzten Commits gezielt zurückrollen. Für noch ältere Stände hast du zusätzlich die Möglichkeit, direkt einen Commit-SHA anzugeben.
Wichtig zu wissen: Dieses Rollback arbeitet additiv. Es wird kein bestehender Verlauf gelöscht. Stattdessen wird, ganz nach Git-Best-Practice, ein neuer Commit erzeugt, der den alten Stand wiederherstellt. Dank der bidirektionalen Arbeitsweise funktioniert das auch andersherum: Ein git revert direkt im Repository wird von der Integration problemlos übernommen.
Vorsicht ist jedoch bei der Funktion Discard Local Changes geboten: Diese verwirft uncommittete Änderungen dauerhaft. Es handelt sich hierbei nicht um ein git revert, und was noch nicht committet wurde, lässt sich danach nicht mehr zurückholen. Für ein sicheres Rollback ist die Commit-Auswahl daher immer der bessere Weg.
Bonus: KI-generierte Commit-Messages
Optional lässt sich ein in Home Assistant eingerichteter Conversation Agent anbinden – egal, ob es sich dabei um ChatGPT, Gemini oder einen lokalen Ollama Agenten handelt. Der Agent erhält den Git-Diff einer Änderung und generiert daraus automatisch eine Commit-Message im sauberen Conventional-Commit-Stil, statt einfach nur eine Standard-Nachricht mit der Dateiliste auszugeben.
Ich selbst nutze dieses Feature nicht, da mir die automatisch generierten Commit-Messages völlig ausreichen. Wer aber ohnehin schon einen Conversation Agent eingerichtet hat, bekommt hier ein spannendes Zusatzfeature. Die Integration funktioniert auch ohne Agenten einwandfrei. Sollte es bei der KI-Anfrage zu einem Fehler kommen, fällt das System automatisch auf die standardmäßige Commit-Message zurück.
Fazit: Lohnt sich git-ha-ppens?
Wichtig vorab: git-ha-ppens ersetzt kein vollständiges Home Assistant Backup. Git sichert lediglich die Konfiguration und die Historie – ein reguläres Backup deiner Instanz bleibt also unerlässlich. Dafür punktet die Integration mit Flexibilität: Sie lässt sich für mehrere Verzeichnisse oder getrennte Repositories einrichten, um beispielsweise die Home Assistant Konfiguration, ESPHome und weitere Projekte sauber getrennt voneinander zu versionieren.
Für mich zeigt dieses Projekt eindrucksvoll, wie viel Kontrolle und Nachvollziehbarkeit man mit ein wenig Git direkt in Home Assistant gewinnen kann – und das ganz ohne zusätzliche Container oder den Zwang, die eigene Instanz einer Cloud anzuvertrauen.
