Botmonster Tech
Posts jQuery Bootpag Categories Tags
Botmonster Tech

Contents

How to Back Up Home Assistant Config to GitHub Automatically

How to Back Up Home Assistant Config to GitHub Automatically

You can secure your Home Assistant configuration by automatically pushing your YAML files to a private GitHub repository on a daily schedule. This gives your smart home version control: you can see exactly what changed between the last working state and the current broken one, roll back a single file in seconds, and rebuild a fresh HA installation entirely from a repository clone. It is faster, leaner, and far more actionable than the built-in snapshot backup for configuration-level problems.

Why Version Control Your Home Assistant Config?

Home Assistant ships with a built-in backup system that creates full .tar snapshots of the entire installation — addons, database, media, and all. Those snapshots are indispensable for full-system disaster recovery: if a drive fails or you migrate to new hardware, a snapshot gets you back to exactly where you were. But they have significant drawbacks when what you actually need is to fix a broken configuration.

A full HA snapshot can run anywhere from 1 GB to 10 GB depending on how much media and database history you have accumulated. Restoring one requires downloading that archive, uploading it through the HA web UI, and waiting through a full restore cycle. If the problem was a single changed line in automations.yaml, that is a sledgehammer solution. You cannot open a snapshot file and read a diff. You cannot restore just one file. You cannot easily answer the question “what exactly changed since this stopped working?”

A Git-backed config repository solves all of these problems. Every automatic commit captures a diff of your entire configuration directory. When your motion-triggered lights stop working after a late-night editing session, git log shows every change made in the last 24 hours. git diff HEAD~1 shows the exact lines modified. git checkout HEAD~1 -- automations.yaml restores only that file to its previous state, and you are back up in seconds without touching your running system.

This is the GitOps principle applied to the smart home: your home’s behavior should be fully reproducible from a single Git repository on a fresh HA installation. The database, media files, and add-on data are ephemeral state; your YAML configuration is the source of truth.

The two approaches complement each other perfectly. Use Git for fast, granular configuration recovery. Use HA’s snapshot backup (or the Backup integration) for full-system disaster recovery when hardware fails.

What to Include (and Exclude) in the Backup

Getting the .gitignore right is the most important security step in this entire setup. Committing the wrong file to a GitHub repository — even a private one — can expose passwords, auth tokens, and device MAC addresses.

Files to track in Git:

  • configuration.yaml — the root configuration file
  • automations.yaml, scripts.yaml, scenes.yaml, groups.yaml — all manually edited automation files
  • ui-lovelace.yaml — if you use YAML mode for your dashboard rather than the GUI editor
  • custom_components/ — any custom integrations you have installed manually
  • themes/ — custom dashboard themes
  • www/ — custom frontend files (images, cards) — consider Git LFS if this folder contains large binaries

Files to exclude from Git (security-critical):

  • secrets.yaml — contains every password, API key, and token referenced by !secret throughout your config; this file must never be committed
  • .storage/ — HA’s internal storage directory holding auth tokens, user credentials, and device registries
  • known_devices.yaml — contains MAC addresses of every tracked device; a privacy leak
  • home-assistant_v2.db — the SQLite history database; large, binary, and full of personal location and sensor data
  • .cloud/ — Nabu Casa credentials

Here is a complete .gitignore file you can copy directly into your HA config directory:

# Sensitive credentials — never commit these
secrets.yaml
known_devices.yaml

# HA internal state storage (tokens, user accounts, device reg)
.storage/
.cloud/

# Database and logs
home-assistant_v2.db
home-assistant_v2.db-shm
home-assistant_v2.db-wal
*.log
OZW_Log.txt

# Backup archives
*.tar
backups/

# Add-on and supervisor state (HA OS only)
deps/
tts/
.uuid
.HA_VERSION

# Python cache
__pycache__/
*.pyc

# Editor junk
.DS_Store
Thumbs.db

Handling secrets.yaml correctly: HA’s !secret syntax lets you replace any sensitive value in your config files with a named reference. For example, api_key: !secret my_weather_api_key in configuration.yaml reads the actual key from secrets.yaml at runtime. This means your committed configuration files are clean, readable, and shareable — the secrets file never needs to leave your local machine. Maintain an encrypted copy of secrets.yaml in a password manager such as Bitwarden or 1Password, and restore it manually when rebuilding on new hardware.

For users who want a more automated approach, Bitwarden Secrets Manager provides a CLI that can generate secrets.yaml from a vault at deployment time. This is the most robust approach for users who manage multiple HA instances or want a fully automated restore pipeline.

Setting Up the GitHub Private Repository

Start by creating a new private repository on GitHub. Log in, click the “+” menu in the top right, and select “New repository.” Name it something descriptive like homeassistant-config, set it to Private, and leave it empty — do not initialize it with a README, because you will be pushing an existing directory.

Next, generate a Personal Access Token (PAT) that the backup process will use to authenticate. Navigate to GitHub → Settings → Developer Settings → Personal Access Tokens. In 2026, prefer Fine-grained personal access tokens over classic tokens, as they can be scoped to a single repository. Set the following permissions on the token:

  • Repository access: Only the homeassistant-config repository
  • Permissions: Contents — Read and Write

This follows the principle of least privilege. A token that can only write to one specific repository causes minimal damage if it is ever leaked. Do not generate a classic token with repo scope across all repositories.

Copy the token immediately — GitHub shows it only once. Store it in your password manager alongside your secrets.yaml backup.

Now add the token to HA’s secrets system so your configuration files can reference it without hardcoding it anywhere. Open HA’s Settings → System → Edit Secrets and add a line:

github_token: ghp_yourTokenHere

Then reference it in your configuration.yaml as !secret github_token wherever needed.

The Home Assistant Git Exporter Add-on

For users running Home Assistant OS or Home Assistant Supervised, the easiest path is the Git Exporter add-on available through the HA Add-on Store . Search for “Git Exporter” in the add-on store and install it.

The add-on configuration is straightforward. In its settings panel, provide:

repository: "https://github.com/USERNAME/homeassistant-config.git"
branch: "main"
username: "your-github-username"
password: "ghp_yourTokenHere"
commit_name: "Home Assistant"
commit_email: "ha@yourdomain.com"
time: "03:00"

The time field schedules the daily backup run. Setting it to 03:00 means the commit happens at 3 AM local time, well outside your active hours. The add-on automatically stages all tracked files, creates a commit with a timestamp message, and pushes to GitHub. On first run, it also initializes the repository and handles the initial commit.

After saving the configuration, click Start and then Open Web UI to trigger a manual run. Check your GitHub repository within a minute — you should see your first commit appear with your configuration files listed. If the push fails, check the add-on logs for authentication errors; the most common cause is a malformed token.

Manual Git Setup for Home Assistant Container Users

Users running HA as a plain Docker container (without the HA OS supervisor layer) do not have access to the add-on store. The setup requires SSH access to the Docker host and a few manual steps.

SSH into the host machine and navigate to your HA configuration directory. This is typically mounted at something like /home/user/.homeassistant/ or wherever you mapped it in your docker-compose.yml:

cd /home/user/.homeassistant/

Initialize the Git repository, add your remote, and create the .gitignore file from the template above:

git init
git remote add origin https://github.com/USERNAME/homeassistant-config.git
git branch -M main

Create and populate .gitignore, then make your initial commit:

git add -A
git commit -m "Initial config backup"
git push -u origin main

When prompted for authentication, use your GitHub username and the PAT token as the password. To avoid being prompted on every push, configure the credential helper:

git config credential.helper store

This stores the credentials in a plaintext file at ~/.git-credentials. On a private server this is acceptable; on a shared machine, consider using an SSH deploy key instead.

Now create the automated backup script. Save this as /home/user/backup_ha_config.sh:

#!/bin/bash

HA_CONFIG_DIR="/home/user/.homeassistant"
LOG_TAG="ha-git-backup"

cd "$HA_CONFIG_DIR" || { logger -t "$LOG_TAG" "ERROR: Cannot cd to $HA_CONFIG_DIR"; exit 1; }

# Stage all changes
git add -A

# Only commit if there are staged changes
if git diff --cached --quiet; then
    logger -t "$LOG_TAG" "No changes to commit."
    exit 0
fi

COMMIT_MSG="Auto backup $(date '+%Y-%m-%d %H:%M:%S')"
git commit -m "$COMMIT_MSG"

if git push origin main; then
    logger -t "$LOG_TAG" "Successfully pushed: $COMMIT_MSG"
else
    logger -t "$LOG_TAG" "ERROR: Push failed"
    exit 1
fi

Make the script executable and set up cron to run it nightly:

chmod +x /home/user/backup_ha_config.sh
crontab -e

Add this line to the crontab, which runs the script at 3 AM every night and appends output to a log file:

0 3 * * * /home/user/backup_ha_config.sh >> /var/log/ha_backup.log 2>&1

You can also trigger the backup on demand from within HA itself. Add the shell_command integration to configuration.yaml:

shell_command:
  backup_config: "/home/user/backup_ha_config.sh"

Then create a script or button helper in HA that calls shell_command.backup_config. This gives you a “Backup Now” button in the UI that you can press before making significant configuration changes.

Handling Large Files with Git LFS

If your www/ or custom_components/ directories contain large binary files — compiled JavaScript bundles for custom Lovelace cards, font files, or large images — standard Git will struggle. GitHub has a 100 MB hard limit per file and starts warning above 50 MB.

Git Large File Storage (LFS) solves this by replacing large files in the repository with lightweight pointers while storing the actual file content on a separate LFS server. Install it on your host and configure tracking for large binary types:

git lfs install
git lfs track "*.woff2"
git lfs track "*.js.map"
git lfs track "www/**/*.png"
git add .gitattributes

Note that GitHub’s free tier includes 1 GB of LFS storage and 1 GB of monthly bandwidth. For most HA configurations this is more than sufficient, but keep it in mind if your www/ folder is unusually large.

Self-Hosted Alternative: Gitea

Users who prefer zero cloud dependency can replace GitHub with a self-hosted Gitea instance running on their local network or a private VPS. Gitea is a lightweight, open-source Git server written in Go that provides a GitHub-compatible API and web interface.

The setup process is identical to the GitHub workflow above. Replace the remote URL with your Gitea instance:

git remote add origin https://gitea.yourdomain.com/USERNAME/homeassistant-config.git

Gitea personal access tokens work exactly like GitHub PATs. For home lab users with a self-hosted server, Gitea is the ideal choice: no data ever leaves your infrastructure, there are no rate limits, and you retain full control over the backup server itself.

Restoring from a GitHub Backup

A backup is only as good as its restore process. Run through this at least once on a spare device or VM before you need it for real.

Scenario 1: Restoring a single broken file after a bad edit.

You changed something in automations.yaml and HA is throwing errors. Find the last known-good commit and restore just that file:

git log --oneline automations.yaml
# Find the commit hash before things broke, e.g. a3f7c12
git checkout a3f7c12 -- automations.yaml

This restores automations.yaml to its state at that commit without touching anything else. Then go to HA’s Developer Tools → YAML → Check Configuration to validate before restarting.

Scenario 2: Full disaster recovery on a fresh HA OS installation.

  1. Install HA OS on the new machine and complete the onboarding wizard minimally.
  2. Enable the SSH add-on from the Add-on Store (it may be in the “Advanced” section).
  3. SSH in and clone your repository:
cd /config
git clone https://github.com/USERNAME/homeassistant-config.git .
  1. Recreate secrets.yaml from your password manager backup — this file is not in Git and must be restored manually.
  2. Run the HA configuration check via Developer Tools, then restart Home Assistant.

Your entire configuration — automations, scripts, scenes, dashboards, custom components — is restored in minutes. What is not restored is your history database (sensor logs, entity history) and any add-on data. Those come from the full snapshot backup, which is why running both strategies in parallel is the recommended approach.

Secrets Management Best Practices

The most dangerous mistake in this workflow is accidentally committing secrets.yaml. It can happen: a misplaced wildcard in .gitignore, a git add -A that picks up a newly created file, a copy of secrets.yaml under a slightly different name. The consequences are severe — GitHub scans all public repositories for leaked credentials automatically, but private repositories have no such protection.

Add a pre-commit hook to catch leaks before they happen. Install git-secrets and register your token patterns:

git secrets --install
git secrets --register-aws  # catches AWS-format keys
git secrets --add 'ghp_[0-9a-zA-Z]{36}'  # catches GitHub PATs

Alternatively, trufflehog can scan your entire commit history for leaked credentials — run it once after the initial setup to confirm nothing sensitive slipped through.

For token rotation: if a GitHub PAT is ever accidentally committed, revoke it immediately in GitHub → Settings → Developer Settings → Personal Access Tokens, generate a new token, and update your HA secrets editor and password manager. Do this before anything else. A revoked token is harmless; an active token in a repository — even a private one — is a live risk.

Finally, apply the two-person rule to your secrets backup. Ensure that at least one other trusted person (a family member, a close colleague) has access to a secure copy of your secrets.yaml or knows how to retrieve it from your password manager. If you are incapacitated and your smart home needs to be restored or handed over, a secrets file locked behind a forgotten master password defeats the entire backup strategy.

Putting It All Together

The complete setup takes about 30 minutes for HA OS users with the Git Exporter add-on, or an hour for Docker container users setting up the manual git workflow. Once running, it operates silently in the background: every morning you have a fresh commit in your private repository capturing exactly what your home automation configuration looked like the night before.

Combined with HA’s native snapshot backup for full-system recovery, this two-tier strategy covers every failure scenario. A broken automation is fixed with a git checkout in seconds. A dead drive is recovered from a snapshot in minutes. Your configuration is documented, diff-able, and version-controlled — the same discipline that makes production software reliable now applied to your home.

 Home-Assistant, Automation, Git, Yaml
 | Home