General

For your repository to be added there are several criteria that need to be met.

General requirements#

Description#

Your repository on GitHub needs to have a description that in a few words describes the purpose of the repository. This description is used in HACS.

Topics#

Your repository on GitHub needs to have topics. Topics are not displayed in HACS, but they can be used for searchability in the HACS store.

README#

Your repository needs to have a readme with information about how to use it. This is not used in HACS, unless you have defined the key render_readme in hacs.json below.

info.md#

If you want to add a richer experience for your users you can add an info.md file to the root of your repository, this file will be rendered under the repository description. It does not support the full styling options from GitHub, so use with care. This is optional, if you do not have this file you need to set the key render_readme in the hacs.json file to true.

See the Templates section on how you can make this awesome

hacs.json#

This is a special manifest file that both defines the information that HACS shows in the UI and what files/paths that HACS should use. This file must be located in the root of your repository.

The following keys are supported:

KeyTypeRequiredDescription
namestringYesThe display name that will be used in the HACS UI.
content_in_rootboolNoIndicates whether the content is in the root of the repository as opposed to in a subdirectory.
zip_releaseboolNoIndicates whether the content is in a zipped archive when releases are published on GitHub. If you use this you also need to add filename. This is only supported for integrations.
filenamestringNoName of the file HACS should look for, only applies to single item categories (plugin, theme, python_scripts, zip_release).
render_readmeboolNoTells HACS to render the README.md file instead of info.md.
domainsstringNoA list of domains.
countrystringNoTwo character country code in ISO 3166-1 alpha-2 format. ISO 3166-1 alpha-2 on Wikipedia
homeassistantstringNoThe minimum required Home Assistant version.
persistent_directorystringNoA relative path (within the integration directory) that will be kept safe during upgrades. Can only be used with integrations.
iot_classstringOnly for integrationsThe type of communication with the service/device. Types used in Home Assistant

examples:

hacs.json
{
"name": "My awesome thing",
"content_in_root": true,
"filename": "my_super_awesome_thing.js",
"country": ["NO", "SE", "DK"]
}
hacs.json
{
"name": "My awesome thing",
"country": "NO",
"domains": ["media_player", "sensor"],
"homeassistant": "0.99.9",
"persistent_directory": "userfiles",
"iot_class": ["Assumed State", "Local Push"]
}

Versions#

If the repository uses GitHub releases, the tagname from the latest release is used to set the remote version. Just publishing tags is not enough, you need to publish releases.

If the repository does not use tags, the 7 first characters of the last commit will be used.

Templates#

You can use Jinja2 templates to control what and how the info is displayed. In addition to the default templates of Jinja these are added:

Template valueDescription
installedTrue / False if it is installed.
pending_updateTrue / False if an update is pending.
prereleaseTrue / False if it's a pre release.
selected_tagThe selected version.
version_availableThe latest available version.
version_installedThe installed version

Examples#

Prerelease#

info.md
{% if prerelease %}
### NB!: This is a Beta version!
{% endif %}

beta

Here Travel Time#

info.md
{% if installed %}
## Changes as compared to your installed version:
### Breaking Changes
### Changes
### Features
{% if version_installed.replace("v", "").replace(".","") | int < 141 %}
- Added `mode: bicycle`
- Added `mode: publicTransportTimeTable` - Please look [here](https://developer.here.com/documentation/routing/topics/public-transport-routing.html) for differences between the two public modes.
{% endif %}
{% if version_installed.replace("v", "").replace(".","") | int < 142 %}
- Release notes are shown in HACS depending on your installed version
{% endif %}
### Bugfixes
{% if version_installed.replace("v", "").replace(".","") | int < 143 %}
- Fix for `mode: publicTransportTimeTable` returning `No timetable route found`
{% endif %}
---
{% endif %}

here

Some examples of info.md files#

Custom Header#

cch

Lovelace Swipe Navigation#

swipe

HomeAssistant-Atrea#

Atrea

Want to add your repository to the store as a default?#

See here for how to add a custom repository.

Badges#

Tell your users that your repository can be tracked with HACS.

Default repository#

If your repository is in the default store.

hacs_badge

[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge)](https://github.com/custom-components/hacs)

hacs_badge

[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/custom-components/hacs)

Custom repository#

If your repository can be added as a custom repository.

hacs_badge

[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge)](https://github.com/custom-components/hacs)

hacs_badge

[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs)
Last updated on