HA GitOps AI Manager

HA GitOps AI Manager is a Home Assistant custom repository that provides controlled GitHub-based versioning, backup, pull/push workflows, rollback safeguards, and AI-agent-friendly configuration management for Home Assistant /config.

Architecture decision (made first)

For Home Assistant OS/Supervised, the most reliable architecture is: add-on plus custom panel.

• A pure custom integration cannot reliably guarantee git binary access and all filesystem/process privileges on every HA OS deployment.
• The add-on provides a stable execution runtime with git + Python tooling and controlled /config access.
• The companion custom component provides native Home Assistant services and a sidebar panel (GitOps AI) while optionally proxying to add-on APIs.

This repository therefore ships both:

1. custom_components/ha_gitops_ai companion integration + panel.
2. addons/ha_gitops_ai_manager add-on backend runtime.

Features

• Connect private GitHub repo (token or SSH) with branch + commit identity.
• Initialize or attach repo for /config or selected subfolder.
• Status: branch, remote, last commit, dirty state, changed files, ahead/behind.
• Manual actions: status, commit, push, fetch, pull, diff, restore file, rollback.
• Safety actions: backup before pull/rollback, config validation, confirmation gates.
• Scheduler: push/fetch/pull/full-cycle with quiet hours and pause toggle.
• Safe mode/lab mode.
• AI Agent Mode: generate AGENTS.md, prompt files, issue/pr templates.
• Protected file handling with warnings and security-focused defaults.

Installation

Option A: HACS custom repository (recommended for panel + services)

1. Add this repo URL in HACS (Integration category).
2. Install HA GitOps AI Manager.
3. Restart Home Assistant.
4. Add integration from Settings → Devices & Services.
5. Open sidebar panel GitOps AI.

Option B: Add-on backend

1. Add this repository as an Add-on repository.
2. Install add-on HA GitOps AI Manager Backend.
3. Configure add-on options (branch, config path, credential mode).
4. Start add-on and enable watchdog/auto-start if desired.

Sidebar pages

• Overview
• Changes
• History
• Push/Pull
• Schedule
• AI Agent Mode
• Protected Files
• Settings
• Logs

Security and safety notes

• Never logs raw GitHub token or SSH private key.
• Warns if tracked files include secrets.yaml or sensitive .storage entries.
• No force push/hard reset by default.
• Pull/rollback can require backup + explicit confirmation.
• Dry-run options supported for pull preview.

Example workflow

1. Configure repo URL + credentials.
2. Initialize git for /config (or selected subfolder).
3. Check status and review changed files.
4. Commit + push local HA changes.
5. Let Codex/AI modify repo remotely via controlled rules.
6. Fetch + diff + validate + pull approved changes back into HA.

AI agent compatibility

Use the AI Agent Mode page or service to generate:

• AGENTS.md
• prompts under .github/prompts/
• issue templates
• pull request template

These templates enforce HA-safe editing rules (no secret edits, preserve entity IDs, validate YAML, modular dashboards, etc.).

Troubleshooting

• If git commands fail in integration mode, run via add-on backend mode.
• If push fails with auth, rotate token and reconfigure credentials.
• If pull fails validation, inspect diff and run HA config check manually.
• If scheduler is paused unexpectedly, verify quiet-hours window and pause toggle.

Development

• Python backend in custom_components/ha_gitops_ai/gitops_manager.py.
• Frontend panel in custom_components/ha_gitops_ai/panel/.
• Add-on backend in addons/ha_gitops_ai_manager/rootfs/usr/src/app/.