MAR.

Using Git and GPG key verified commits to backup your Home Assistant config

Miguel A Rios -

Out of desire to learn how to use Git, I decided to try learning it by using it for my Home Assistant config. I think Git is a good system to learn in general, and it has a variety of uses such as managing a static website, or for documentation. I will try to explain what my current setup is, what bumps I hit, and what lessons I learned. There is an older post for how to use Git with Home Assistant, but my setup was a bit different.

Prerequisites:

  • Github account - obviously
  • Public or Private repo - You can always switch if you later change your mind, but keep in mind there are some differences
  • Access to your Home Assistant setup via SSH or SMB - Important so that you don't have to clone your repo locally and then have to pull changes where your Home Assistant config lives.
  • VS Code - Not really important, but this my favorite text editor on Mac.

My setup is Home Assistant installed via Docker on my unRAID box and accessible via SMB on my Mac.

Contents:

  1. Mistakes / Troubleshooting
  2. Future improvements

Setup Git and connect to github

Git comes preinstalled on Mac usually, but if not it is super easy to install if you have Homebrew all you have to do is type brew install git in your terminal, and you're off to the races.

To setup Git with your Github account I just used the instructions from the Git Getting Started Book, it is an excellent resource to get started. Now for me I didn't want to use my real email for commits, so I chose to no-reply email github provides. Here is some information on your commit email  and how to set it up if you want a similar setup to mine.

Setup GPG key for commit verifying

Having commits be verified are important for security. Here is how to do it on Mac.

Install the latest version of GnuPG which is version 2.

brew install gpg2

After install double check you have version 2.x.

gpg --version

If the above command does not work try it with gpg2

Whichever one works make sure to configure git to tell it which program to use for signing.

git config --global gpg.program gpg

On Mac you will not be asked for a passphrase without this utility, at least not for me and not at the time of making this post. For that install this utility.

brew install pinentry-mac

I followed github's documentation, to create my GPG key, add to github, add to git, and to associate my commit email from github with git. Go ahead and follow that guide. Some things to keep in mind though:

  • For the key I went with 4k RSA.
  • If you are keeping your email anonymous on github then remember that you need to make sure your GPG key email and git all use the same email.
  • To set git to auto sign your commits add git config commit.gpgsign true.

Once you are done you should be setup to create your first commit. Go ahead and try it and you should see a prompt come up to enter your passphrase.

If you get the following error

error: gpg failed to sign the data
fatal: failed to write commit object

Try and enter the following command that I found from this post. Then try your commit again.

echo "pinentry-program /usr/local/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf

Backup your Keys and Passphrase

It goes without saying that you should backup your passphrase somewhere like a password manager because you will need this often. However it doesn't hurt to save a copy of my public and private GPG key, just incase. This would come in handy if you want to work on a separate machine and also verify you commit there too with the same key.

First obtain your key ID

gpg --list-secret-keys --keyid-format LONG

Export your keys in binary (.gpg) and ASCII or Armored format by adding -a before --export and using extension .asc.

gpg --export [email or key ID] > public.gpg
or
gpg --o public.gpg --export [email or key ID]

To backup your secret key use the same as above except use --export-secret-keys instead of --export.

Backup Home Assistant

To backup my Home Assistant config you first need to create a .gitignore file. Make sure you are using the secrets.yaml extensively. Add to your .gitignore file items such as:

# Whitelisted files files that you want to include in your commit

!*.yaml
!.gitignore
!*.md


# Directories you want to remove such as the following:

.cloud
.storage
.vscode
custom_components
deps
image
tts

# Wildcard files that aren't good to backup for privacy
*.xml
*.db
*.sqlite
*.log


# Any specific files that you want to exclude
secrets.yaml
configuration/zone.yaml
configuration/notify.yaml
configuration/media_player.yaml
configuration/device_tracker.yaml

Then all you need to do is, while in the directory you want to backup, typing git init will create a .git file to start tracking changes. To make your initial commit you type git add . and followed by git commit -m "[YOU COMMIT MESSAGE]" and finally git push origin master.

Mistakes / Troubleshooting

Below are a few errors that I experienced that can hopefully help you diagnose

How to deal with .fuse_hidden file

I use unRAID as my docker host for my Home Assistant. I then mount the appdata folder that contains my Home Assistant config folder to my Mac. I experienced issues when I wanted to delete my .git to start over where a non-existent file would appear called something like .fuse_hiddenXXXXXX. This file would refuse to be deleted. What I discovered is that you have to use lsof to figure out what service is still using your file. When I ran lsof I found out that SMB was the culprit which meant I had to do a restart of my server. This let go of this file and it was successfully removed. Below are some sites that I used for reference.

Refresh Gitignore file

Using .gitignore is very important when you are adding files to a publicly accessible repository site like Github. You are bound to add more information to your .gitignore file. When you do you need to make sure that you clear the cache before doing a commit when you have editted the .gitignore file because if you do not then you are risking publicizing.

Make sure to run git rm -r --cached . followed by adding your changes git add . and

How to change your email associated with your GPG key

If you ever need to change your email associated with your GPG key then enter gpg --edit-key <keyID> followed by adduid you will then enter your new information which if you are just changing your email add everything else the same. Continue by updating the trust level of your new uid followed by revoking the old uid.

References