Sharing your configuration on GitHub

:warning: This guide has been migrated from our website and might be outdated. Feel free to edit this guide to update it, and to remove this message after that.

Sharing and regularly syncing your Home Assistant configuration to GitHub has several benefits:

  • A remote copy of your Home Assistant YAML files in case you need to recover.
  • A documented history of your changes for troubleshooting purposes.
  • It will help the Home Assistant community learn from your configuration examples.

:information_source: This is not a comprehensive tutorial on using GitHub, more information can be found in the GitHub Help pages. This guide assumes the user has an intermediate experience level and is comfortable with such concepts as: navigating the Home Assistant directory structure, logging in as the Home Assistant user, and working with the command line.


:warning: This will not create a full backup of your Home Assistant files or your Operating System. In addition to backing up to Github, you should consider having regular backups of all your Home Assistant configuration files using Snapshots or by having images of your SD card.


Important Best Practices

Some best practices to consider before putting your configuration on GitHub:

  • Extensive use of secrets.yaml to hide sensitive information like usernames, passwords, device information, and location.

  • Exclusion of some files, including secrets.yaml and device-specific information using a .gitignore file.

  • Regularly committing your configuration to GitHub to make sure that your backup is up to date.

  • Use a README.md to document your configuration and include screenshots of your Home Assistant frontend.

Step 1: Installing and Initializing Git

In order to put your configuration on GitHub, you must install the Git package on your Home Assistant server (instructions below will work on Raspberry Pi, Ubuntu or any Debian-based system) Note: this isn’t required in Hass.io, it’s included as default so proceed to step 2:

sudo apt-get update
sudo apt-get install git

Step 2: Creating .gitignore


:warning: Before creating and pushing your Home Assistant configuration to GitHub, please make sure to follow the secrets.yaml best practice mentioned above and scrub your configuration for any passwords or sensitive information.


Creating a .gitignore file in your repository will tell Git which files NOT to push to the GitHub server. This should be used to prevent publishing sensitive files to the public. It should contain a list of filenames and pattern matches. This list should include at least your secrets.yaml file, device configuration files, and the Home Assistant database/directory structure. The .gitignore file should be placed in the root of your Home Assistant configuration directory: <config dir>/.gitignore.

Here is an example that will ignore everything but your YAML configuration.

# Example .gitignore file for your config dir.
# An * ensures that everything will be ignored.
*
# You can whitelist files/folders with !, these will not be ignored.
!*.yaml
!.gitignore
!*.md

# Ignore folders.
.storage
.cloud
.google.token

# Ensure these YAML files are ignored, otherwise your secret data/credentials will leak.
ip_bans.yaml
secrets.yaml
known_devices.yaml

:warning: You might read this guide too late and accidentally already have your secrets published. It is not enough to just remove them with a new commit. Git is a version control system and keeps history. You need to delete your repository and start a new one. Also change all passwords and revoke the API keys that were public.


More information on the layout of the file can be found in the .gitignore manual.

Step 3: Preparing your Home Assistant directory for GitHub

In your Home Assistant directory, type the following commands as the Home Assistant user, replacing the email address and name with your information:

git init
git config user.email "[email protected]"
git config user.name "Your Name"
git add .
git commit

After the git commit command, you will be asked to enter a message for the commit. This will add a comment beside each file on GitHub describing the purpose of the commit. In this case, you can enter something like “Initial commit of my Home Assistant configuration”. To exit the editor, press CTRL + C and then :wq which will exit and save the changes.

Step 4: Creating Repository on GitHub

  • Connect to GitHub and login to your account (or create an account if you don’t already have one).

  • Click “New Repository” and give your repository a name/description (Home-AssistantConfig is used in the example below). You do NOT need to change any other options.

  • Click “Create Repository”

Step 5: Your initial commit to GitHub

Once you are sure you are using secrets.yaml and .gitignore correctly, it is time to push your configuration to the GitHub Repository that you just created.

In your Home Assistant directory, type the following commands as the Home Assistant user, replacing “username” in the URL with your GitHub username:

git remote add origin https://github.com/username/Home-AssistantConfig
git push -u origin master

You will be asked to enter your GitHub username and password (or ssh key passphrase if you use GitHub with ssh).

Congratulations, you now have a copy of your current Home Assistant Configuration on GitHub!

Step 6: Keeping your repository up to date

You should update your repository on a regular basis. Ideally after you make a major configuration change (new device, new component, etc.). The below script will update your repository with any changed configuration files and allow you to add a comment with the commit for tracking purposes:

:information_source: You may need to adjust the paths in the script depending on your Home Assistant configuration.

gitupdate.sh:

#!/bin/bash

cd /home/homeassistant/.homeassistant
source /srv/homeassistant/bin/activate
hass --script check_config

git add .
git status

echo -n "Enter the Description for the Change: " [Minor Update]
read CHANGE_MSG

git commit -m "${CHANGE_MSG}"
git push origin master
exit

Every time you run this script, you will be prompted for a comment to describe the change(s) that you are committing. This comment will be displayed beside each changed file on GitHub and will be stored after each commit. You will also be asked to enter your GitHub username and password (or SSH key passphrase if you use GitHub with SSH).

Step 7: Configuration file testing

Travis CI is a continuous integration testing system that runs every time the code in your repository is updated and allows you to validate that your code works on a fresh install.

  • Authorize Travis CI to have access to your GitHub repositories.

  • Create the build script that Travis will run to test your repository.

  • Create a dummy secrets.yaml for Travis.

Example .travis.yml

language: python
python:
- "3.7"
before_install:
- mv travis_secrets.yaml secrets.yaml
- sudo apt-get install -y libudev-dev
install:
- pip3 install homeassistant
script:
- hass -c . --script check_config

Since the secrets.yaml should not be stored in your repository for security reasons, you won’t be able to access it at build time. Creating a dummy secrets.yaml is as simple as creating a new file that mimics your existing secrets.yaml with the required keys, but not their value.

#travis_secrets.yaml
http_api: 000000000000000000000000
home_latitude: 00.00000
home_longitude: 00.0000
home_elevation: 0

Extra commands

You can enter these commands to get a list of the files in your local Git repository and a status of files that have changed but not committed yet:

git ls-files
git status

Examples:

homeassistant@raspberrypi:~/.homeassistant $ git ls-files
.gitignore
README.md
automation.yaml
configuration.yaml
customize.yaml
device_tracker.yaml
group.yaml
script.yaml

homeassistant@raspberrypi:~/.homeassistant $ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:

(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: .gitignore
modified: automation.yaml
modified: customize.yaml
modified: group.yaml

no changes added to commit (use "git add" and/or "git commit -a")
19 Likes

Awesome guide, thanks.

Everything works for me from the command line but I get this error if trying to push via the File Editor in the UI. Any idea why?

Hello i have the same problem than you this appen when i try to use git in file edit can someone help

Same error. Can we use git with File Editor?

You have that error with File Editor, because file editor is running in the separate container.
The best thing you can do, imo:

  1. create shell command
  2. create script, that runs your shell command (for easyu calling)
  3. run scripts for pulling and pushing your changes.

Remember: file editor can do commit, but it refuses to do git add . so you have to do that before push
My config:
configuration.yaml

...
shell_command: !include shell.yaml
...
logger:
 ...
  logs:
    ...
    homeassistant.components.shell_command: debug #for reading stdout and stderr of our commands

shell.yaml (call cd for correct working dir)

update_config: cd /config && bash ./shell/update.sh 
store_config: cd /config && bash ./shell/update_remote.sh

update.sh

git pull

update_remote.sh

# commit changes over file editor and than run update_remote.sh
message=$(git log -1 --pretty=%B | cat) #read last commit message made in file editor
git add . && git commit --amend -m "${message}" && git push #ammend changes, cause of stupidity of file editor

You need create ssh key and put it inside you main container.
The easiest way is use one of just created shell commands.
First of all generate new ssh key inside your main container:

ssh-keygen -q -t rsa -N '' -f ~/.ssh/id_rsa <<<y 2>&1 >/dev/null && cat ~/.ssh/ida_rsa.pub

This will create ssh key and output it’s public string. (first part explanation here)
Add public string to github account to allow ssh git interaction.
Than you need add github.com to known hosts.

ssh-keyscan github.com >> ~/.ssh/known_hosts

Okay. Now you have your key available in main container and you will have no problem with pull & push interactions.

You will see in core logs command output, when run your scripts.
Remember output is escaped. All new lines will be replaces with \n symbol.

Good luck

Can anyone comment on the quality of the .gitignore file from gitignore.io?

# Created by https://www.toptal.com/developers/gitignore/api/homeassistant
# Edit at https://www.toptal.com/developers/gitignore?templates=homeassistant

### HomeAssistant ###
# Files with personal details
*.crt
*.csr
*.key
.google.token
.uuid
icloud/
google_calendars.yaml
harmony_media_room.conf
home-assistant.db
home-assistant_v2.db
home-assistant_v2.db-*
html5_push_registrations.conf
ip_bans.yaml
known_devices.yaml
phue.conf
plex.conf
pyozw.sqlite
secrets.yaml
tradfri.conf

# Temporary files
*.db-journal
*.pid
tts

# automatically downloaded dependencies
deps
lib
www

# Log files
home-assistant.log
ozw_log.txt

# Development files
custom_components/

# End of https://www.toptal.com/developers/gitignore/api/homeassistant

This is the files it would track in my setup:

.HA_VERSION
.gitignore
.shopping_list.json
.storage/
automations.yaml
blueprints/
bosch_shc/
configuration.yaml
customize.yaml
groups.yaml
image/
scenes.yaml
scripts.yaml

from these files and folders being available:

.HA_VERSION
.cloud/
.git/
.gitignore
.shopping_list.json
.storage/
automations.yaml
blueprints/
bosch_shc/
configuration.yaml
customize.yaml
deps/
groups.yaml
home-assistant.log
home-assistant_v2.db
home-assistant_v2.db-shm
home-assistant_v2.db-wal
html5_push_registrations.conf
image/
ip_bans.yaml
known_devices.yaml
scenes.yaml
scripts.yaml
secrets.yaml
tts/

It does not exclude folders like .storage. Is this a bad thing? To my understanding, many configurational options are set in this folder (and not in the yaml files in the config base dir) – in theory one should want to have those tracked as well, no?

It also tracks .HA_VERSION. While I see a benefit from this on the one side (to know what version the config was set up for), I can also imagine that one can run into problems when pulling to host with different version (which might also be a good thing in the end :slight_smile: )

Happy for any comments!

Yes, you are right - .storage (IMHO) should also be excluded - it includes a lot of your configuration information (private data) out of which some can be misused.

I think a better approach would be to ignore everything in the .gitignore and then exclude only selected directories and filetypes from it.
it saves you a lot of time in the long run and is more robust against changes and safe to use with automatic processes. It’s especially useful when using very ambitious split configurations.

In other words: use a whitelist not a blacklist

#example .gitignore

#ignore everything
*

#whitelist main configuration
!configuration.yaml

#whitelist yaml files in subdirectory integrations
!integrations/
!integrations/*.yaml

#whitelist esphome subdirectory 
!esphome/
!esphome/*.yaml
!esphome/*.h
4 Likes

It all depends how your configuration looks and if you run some actions against your repository or not. I do check each commit against HA latest, dev and beta version.

For ex. in my case, I would have to do a lot of whitelisting - much more then all of the blacklisting I have:

I found an error in the suggested .gitignore: known_devices.yaml should be known-devices.yaml (at least for Container hosting). I don’t have an ip_bans.yaml, so I don’t know if the underscore should be a hyphen there also.
The error is hidden because the the “ignore everything”, but the last ignores should either work or be removed.

my config folder has

known_devices.yaml

HI
I’ve been using this to push my config to github through HA → terminal
IT worked for some years, but now i cant push commit using username and password
It seems i need to have a token or smth

Can anyone help me pls how i do that?

Anyone can help me?

Hi skank,

your question is perfectly covered in the initial post.

Check these docs:

Someone else helped me and its ok now

Nice thread you guys have going here. I’ve learned a lot about what files “not to share”. I’m getting this error when trying to upload to remote repository on git:

remote: error: See http://git.io/iEPt8g for more information.
remote: error: File home-assistant_v2.db is 134.86 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.

Is this db file not supposed to be synchronized? I’m aware git-lfs is not added to the base image. Is this needed?

You shouldn’t sync .db - add it to ignore list.

I know that adding to git the custom_components/ it is not a good practice, but if I install them with HACS, how can I obtain a consistent backup/restore versioning without manual steps, that also properly restores also the plugins installed using HACS?

Moreover for many integrations, mainly not official such as Scheduler or Alarmo, it is not clear (without reversing the source code, of course) how to add the integrations in the yaml without further actions on the UI (which are written in .storage/ folder).

What is your approach?

Hi There,

I feel a bit stupid. I accidentally pressed git init and now most of my files in the config folder have turned red. I have a git hub account but I do not have the github integration setup in HA so I assume that these files are red because they are not being uploaded.

I have tried restoring a backup to before this accidental button press but the files remain red.

Is there anyway to roll this back?

thanks in advance.

mark this blogpost