GitOps for Home Assistant — right from your UI.
GitOps for Home Assistant. Edit your config in VS Code or directly on GitHub, push the changes, and your HA instance pulls them automatically. Roll back any breaking change by reverting a commit. Review config changes in a pull request before they ever reach your live system.
git-ha-ppens brings native git directly into Home Assistant — auto-commit on file change, auto-push to your remote, and now auto-pull when new commits arrive. All configured through the UI, no command line needed.
- ✨ Features
- 🔁 GitOps Workflow
- 📥 Installation
- ⚙️ Configuration
- 🤖 AI Commit-Messages
- 🚀 Services
- 📊 Sensors & Entities
- ⚡ Events
- 💡 Example Automations
- 🛡️ Auto-Generated .gitignore
- 🔧 Troubleshooting
- 🤝 Contributing
- 📄 License
- 👁️ File watcher detects config changes in real time (powered by watchdog)
- ⏱️ Configurable debounce interval (default 5 min) to batch changes and avoid excessive commits
- 📝 Auto-generated commit messages listing the changed files
- 🔄 Periodic git fetch checks the remote on a configurable interval (default 5 min, range 60–3600s)
- ⬇️ Auto-pull when the integration detects your instance is behind the remote
- ⬆️ Auto-push after every auto-commit to keep the remote up to date
- ✅ Pre-deploy check (optional) — validates the Home Assistant configuration after pulling and automatically rolls back if the check fails, so broken remote changes never reach your live system
- 7 services callable from automations, scripts, or Developer Tools:
git_ha_ppens.commit— create a commit with an optional custom messagegit_ha_ppens.push— push commits to the configured remotegit_ha_ppens.pull— pull from remote (auto-backs up uncommitted changes first)git_ha_ppens.fetch— fetch from remote without merging (updates ahead/behind counts)git_ha_ppens.sync— commit + push in one stepgit_ha_ppens.diff— get the current diff of uncommitted changesgit_ha_ppens.discard_changes— discard tracked local changes
- 4 buttons on the integration device page for Push, Pull, Fetch, and optionally discarding local changes
- 🚫 Automatic
.gitignoreforsecrets.yaml,.storage/, databases, logs, and more - 🔍 Secret detection scans tracked files for API keys, tokens, and passwords
- 🔔 Fires a
git_ha_ppens_secret_detectedevent when potential secrets are found
- Push and pull from GitHub, GitLab, Bitbucket, or any git remote
- HTTPS with personal access token or SSH key authentication
- 10 sensors + 1 binary sensor for real-time git status
- 4 buttons for Push, Pull, Fetch, and optionally discarding local changes
- Events for commit, push, pull, fetch, errors, and secret detection
- Build dashboards, notifications, and automations around your config history
- Full diagnostics support via Settings → Devices & Services → git-ha-ppens → Diagnostics
- Sensitive values are automatically redacted
GitOps means your git repository is the single source of truth for your Home Assistant configuration. Instead of editing files directly on your HA instance, you manage changes through git — and your instance automatically stays in sync.
With git-ha-ppens you get a full GitOps loop without any extra tooling:
Edit config in VS Code / GitHub → push to remote
↓
git-ha-ppens fetches periodically (default: every 5 min)
↓
Detects your instance is behind → auto-pull
↓
(optional) Pre-deploy check → rollback if config is invalid
↓
Home Assistant is up to date ✓
- Edit from anywhere — use your local editor, the GitHub web UI, or any other git client. Changes reach HA automatically.
- Review before it goes live — open a pull request for config changes and merge only when you're ready.
- Instant rollback — revert a commit on GitHub and your HA instance pulls the rollback automatically.
- Safe deploys — enable the optional pre-deploy check to run a Home Assistant configuration check on incoming changes. If it fails, the pull is rolled back automatically and your instance keeps running on the last working config.
- Full history — every config change is a commit. Know exactly what changed, when, and why.
- Configure a remote repository (GitHub, GitLab, etc.) in the integration setup
- Enable Auto-Pull in the commit settings
- Set a Fetch Interval (default 5 min) so the integration checks for remote changes periodically
- Optionally enable Auto-Push to send local changes upstream automatically
- Optionally enable the Pre-deploy check to validate incoming changes and roll back automatically if the config is broken
That's it. From this point on, your HA config and your git remote stay in sync automatically.
🛡️ Pre-deploy check: When enabled, every pull (manual or automatic) runs a Home Assistant configuration check after merging. If the check reports errors, git-ha-ppens performs a
git reset --hardback to the last working commit, fires agit_ha_ppens_check_failedevent, and creates a persistent notification listing the errors — so a bad commit on the remote can't take down your instance. This check validates the live configuration directory, so it only runs whenrepo_pathis your HA config directory (e.g./config).
Requirements:
- 🏠 Home Assistant 2024.1 or later
- 🔧 Git installed on the host system
HA OS users: Git may not be available by default. You may need a dedicated add-on or container with git pre-installed.
- Make sure HACS is installed
- Click the badge above — or go to HACS → Integrations → ⋮ → Custom repositories and add:
with category Integration
https://github.com/manuveli/git-ha-ppens - Search for git-ha-ppens and click Install
- Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration and search for git-ha-ppens
- Download the latest release from the Releases page
- Copy the
custom_components/git_ha_ppensfolder into yourconfig/custom_components/directory - Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration and search for git-ha-ppens
The integration is configured entirely through the UI. The setup flow has 3 steps:
| Option | Description | Default |
|---|---|---|
repo_path |
Path to the HA configuration directory | /config |
git_user |
Git author name for commits | (required) |
git_email |
Git author email for commits | (required) |
| Option | Description | Default |
|---|---|---|
auto_commit |
Automatically commit when files change | true |
auto_push |
Push to remote after each auto-commit | true |
auto_pull |
Pull automatically when the instance is behind the remote | false |
pre_deploy_check |
Run a HA config check after pulling and roll back if it fails | false |
commit_interval |
Debounce interval in seconds (30–86400) | 300 |
scan_interval |
Status polling interval in seconds (10–3600) | 30 |
fetch_interval |
How often to fetch from remote in seconds (60–3600) | 300 |
| Option | Description | Default |
|---|---|---|
remote_url |
Git remote URL (HTTPS or SSH) | (empty) |
auth_method |
none / token / ssh |
none |
auth_token |
Personal access token (for HTTPS) | (empty) |
ssh_key_path |
Path to SSH private key file | (empty) |
💡 Tip: All settings can be changed later via Settings → Devices & Services → git-ha-ppens → Configure. The options menu provides two sections: General Settings (all configuration options above) and Edit .gitignore (a built-in editor for customizing ignored files).
By default, git-ha-ppens generates simple commit messages listing the changed files — for example Auto: config.yaml changed or Auto: 3 files changed. This works great out of the box and does not require any AI setup.
If you want more descriptive, context-aware commit messages, you can optionally enable AI-generated commit messages. The integration uses Home Assistant's built-in Conversation service to analyze the git diff and generate a meaningful commit message — powered by whichever AI agent you have configured in HA (OpenAI, Google Generative AI, Ollama, etc.).
AI commit messages can be enabled during the initial setup (Step 2: Auto-Commit Settings) or at any time later via Settings → Devices & Services → git-ha-ppens → Configure.
| Option | Description | Default |
|---|---|---|
ai_commit_messages |
Enable AI-generated commit messages | false |
ai_agent_id |
Entity ID of the conversation agent to use (e.g. conversation.chatgpt) |
(empty) |
💡 Tip: Leave
ai_agent_idempty to use Home Assistant's default conversation agent. If you have multiple AI agents configured, you can specify exactly which one should generate your commit messages.
AI commit messages are designed to never interfere with normal operation:
- 🔒 If AI is disabled (default), the integration works exactly as before — no AI code is executed at all
⚠️ If AI is enabled but the conversation agent is unavailable or returns an error, the integration silently falls back to the standard auto-generated message- ✅ Commits are never blocked by AI failures — your configuration changes are always saved regardless of AI availability
📌 No AI? No problem. The integration is fully functional without any AI agent configured. The AI feature is a purely optional enhancement.
The git-ha-ppens device page provides an optional Discard Local Changes button. When a remote repository is configured, it also provides Push, Pull, and Fetch buttons under Controls. The Push button first commits all pending changes using the configured standard or AI commit-message behavior, then immediately pushes them to the remote. Pull and Fetch run the same operations as the corresponding services below.
The destructive Discard Local Changes button is disabled by default and
must be enabled from its entity settings. It restores staged and unstaged
changes to tracked files back to HEAD. Untracked files are preserved. This is
not git revert, does not reset to the remote branch, and cannot undo a change
after auto-commit has already created a commit.
| Service | Description | Parameters |
|---|---|---|
git_ha_ppens.commit |
Stage all changes and create a commit | message (optional) — custom commit message |
git_ha_ppens.push |
Push commits to the configured remote | — |
git_ha_ppens.pull |
Pull from remote (backs up uncommitted changes first) | — |
git_ha_ppens.fetch |
Fetch from remote without merging — updates the ahead/behind counts | — |
git_ha_ppens.discard_changes |
Permanently discard staged and unstaged changes to tracked files; untracked files are preserved | — |
git_ha_ppens.sync |
Commit + push in one step | message (optional) — custom commit message |
git_ha_ppens.diff |
Get the current diff of uncommitted changes | — (returns response data) |
action:
- service: git_ha_ppens.sync
data:
message: "Manual sync from automation"The diff service returns response data containing the diff content and a status summary. Use it in scripts or automations to inspect changes before committing.
action:
- service: git_ha_ppens.diff
response_variable: git_diff| Entity | Description | Attributes |
|---|---|---|
sensor.git_ha_ppens_last_commit |
Last commit hash (short) | message, author, full_hash |
sensor.git_ha_ppens_last_commit_time |
Timestamp of last commit | — |
sensor.git_ha_ppens_uncommitted_changes |
Number of changed files | changed_files, untracked_files, staged_files |
sensor.git_ha_ppens_branch |
Current branch name | — |
sensor.git_ha_ppens_remote_status |
Sync status (e.g. "in sync", "ahead 3") | ahead, behind, remote_configured, has_upstream, total_commits |
sensor.git_ha_ppens_commits_ahead |
Number of local commits not yet pushed | — |
sensor.git_ha_ppens_commits_behind |
Number of remote commits not yet pulled | — |
sensor.git_ha_ppens_last_fetch_time |
Timestamp of last successful fetch | — |
sensor.git_ha_ppens_last_pull_time |
Timestamp of last successful pull | — |
sensor.git_ha_ppens_last_push_time |
Timestamp of last successful push | — |
| Entity | Description | Device Class |
|---|---|---|
binary_sensor.git_ha_ppens_dirty |
on when there are uncommitted changes |
problem |
Use these events as automation triggers to build notifications, dashboards, or recovery workflows.
| Event | Fired when | Data |
|---|---|---|
git_ha_ppens_commit |
A commit is created | hash, message, author, changed_files, auto |
git_ha_ppens_push |
Commits are pushed | commits_pushed |
git_ha_ppens_pull |
Commits are pulled | commits_pulled, changed_files, auto |
git_ha_ppens_fetch |
A fetch completes | — |
git_ha_ppens_check_failed |
A pull was blocked and rolled back by the pre-deploy check | errors, auto |
git_ha_ppens_error |
A git operation fails | operation, error |
git_ha_ppens_secret_detected |
Potential secrets found in tracked files | findings, count |
A useful GitOps signal: let HA notify you when new commits are available on the remote but haven't been pulled yet (e.g. if auto-pull is disabled).
automation:
- alias: "Git: Notify when behind remote"
trigger:
- platform: numeric_state
entity_id: sensor.git_ha_ppens_commits_behind
above: 0
action:
- service: notify.mobile_app
data:
title: "git-ha-ppens"
message: "{{ states('sensor.git_ha_ppens_commits_behind') }} new commit(s) available on the remote."automation:
- alias: "Git: Push after commit"
trigger:
- platform: state
entity_id: sensor.git_ha_ppens_last_commit
action:
- service: git_ha_ppens.pushautomation:
- alias: "Git: Remind to commit"
trigger:
- platform: state
entity_id: binary_sensor.git_ha_ppens_dirty
to: "on"
for: "01:00:00"
action:
- service: notify.mobile_app
data:
title: "git-ha-ppens"
message: "You have uncommitted configuration changes."automation:
- alias: "Git: Weekly snapshot"
trigger:
- platform: time
at: "02:00:00"
condition:
- condition: time
weekday:
- sun
action:
- service: git_ha_ppens.commit
data:
message: "Weekly config snapshot"automation:
- alias: "Git: Secret detected alert"
trigger:
- platform: event
event_type: git_ha_ppens_secret_detected
action:
- service: notify.mobile_app
data:
title: "⚠️ git-ha-ppens Security Alert"
message: "Found {{ trigger.event.data.count }} potential secret(s) in tracked files!"automation:
- alias: "Git: Pre-deploy check blocked a pull"
trigger:
- platform: event
event_type: git_ha_ppens_check_failed
action:
- service: notify.mobile_app
data:
title: "🛡️ git-ha-ppens: Pull blocked"
message: >-
Config check failed, rolled back to the last working state:
{{ trigger.event.data.errors | join(', ') }}The integration automatically creates a .gitignore with sensible defaults for Home Assistant on first setup.
You can customize the .gitignore entries at any time via Settings → Devices & Services → git-ha-ppens → Configure → Edit .gitignore. The built-in editor lets you add, remove, or modify entries directly from the UI.
| Category | Entries |
|---|---|
| Sensitive files | secrets.yaml, .storage/, .cloud/, tls/, .ssh/, .jwt_secret, SERVICE_ACCOUNT.json |
| Databases & logs | *.db, *.db-shm, *.db-wal, *.log, home-assistant_v2.db, home-assistant.log*, zigbee.db, OZW_Log.txt |
| System files | .HA_VERSION, known_devices.yaml, ip_bans.yaml |
| Python cache | __pycache__/, *.pyc, *.pyo |
| Runtime & other | .git/, deps/, tts/, .venv/, .cache/, .claude/, custom_components/, www/snapshots/, .ha_run.lock, .exports, .timeline, .vacuum |
| Zigbee2MQTT | zigbee2mqtt/state.json, zigbee2mqtt/coordinator_backup.json |
| Editor swap files | *.swp, *.swo |
📌 Defaults are applied once during initial setup. After that, you can freely edit
.gitignore— your changes will be preserved across restarts.
❌ "Git is not installed"
Home Assistant OS does not include git by default. Options:
- Use a container/add-on that includes git
- Install git via the SSH & Web Terminal add-on:
apk add git
❌ Push fails with "permission denied" or "403"
- Verify your personal access token has the
reposcope - Check that the remote URL is correct and the repository exists
- For SSH: ensure the key path is valid and the key is added to your git provider
❌ "Remote origin is not configured"
Go to Settings → Devices & Services → git-ha-ppens → Configure and set a remote URL in the options flow.
❌ Auto-commit not triggering
- Verify
auto_commitis enabled in the integration options - Check that the changed files are not in
.gitignoreor the watcher's ignore patterns (.git,.storage,.ssh,__pycache__,*.db,*.log, etc.) - Review HA logs for file watcher errors
❌ "Secrets detected" warning
- Review the flagged files and move sensitive values to
secrets.yaml - Ensure
secrets.yamlis listed in.gitignore(it is by default) - The detection uses regex patterns for common key formats (API keys, tokens, passwords)
Contributions are welcome! Whether it's bug reports, feature requests, or pull requests — feel free to get involved.
- 🐛 Bug reports & feature requests: GitHub Issues
- 🔀 Pull requests: Fork, create a branch, and submit a PR
- Clone this repository
- Symlink or copy
custom_components/git_ha_ppensinto your HA dev instance'scustom_components/directory - Restart Home Assistant
- Follow Home Assistant's coding conventions (
ruff,mypy)
This project is licensed under the MIT License.
Made with ❤️ for the Home Assistant community
github.com/manuveli/git-ha-ppens
