ha-hacs

HACS Metadata Guide

HACS (Home Assistant Community Store) is the standard distribution method for custom integrations.

Repository Structure

my-integration/
├── custom_components/
│   └── {domain}/
│       ├── __init__.py
│       ├── manifest.json      # HA manifest (required)
│       ├── config_flow.py
│       └── ...
├── hacs.json                  # HACS metadata (required)
├── README.md                  # Documentation (required)
├── LICENSE                    # License file (recommended)
└── .github/
    └── workflows/
        └── validate.yml       # HACS validation workflow

manifest.json Requirements

HACS requires these fields in manifest.json:

{
	"domain": "my_integration",
	"name": "My Integration",
	"version": "1.0.0",
	"codeowners": ["@your-github-username"],
	"documentation": "https://github.com/user/repo",
	"issue_tracker": "https://github.com/user/repo/issues",
	"config_flow": true,
	"integration_type": "hub",
	"iot_class": "local_polling",
	"requirements": ["my-library==1.0.0"]
}

Required for HACS:

• domain — Must match folder name
• name — Display name
• version — Valid semver (X.Y.Z); required in manifest.json for HACS custom integrations, but must be omitted for HA core integrations
• codeowners — At least one GitHub username
• documentation — URL to docs
• issue_tracker — URL for bug reports

The list above is the HACS-metadata-required set. Separately, integration_type and iot_class are required by hassfest, and the HACS validation action runs hassfest — so a HACS-targeting repo needs them too (iot_class must be one of the accepted values; integration_type is validated strictly when present).

hacs.json Configuration

Create hacs.json in repository root:

{ "name": "My Integration", "homeassistant": "2025.1.0" }

Common hacs.json Options

Key	Type	Required	Description
name	string	Yes	Display name in HACS
homeassistant	string	No	Minimum HA version (e.g., "2025.1.0")
hacs	string	No	Minimum HACS version
content_in_root	bool	No	Set true if files not in custom_components/
zip_release	bool	No	Set true if using zipped releases
filename	string	No	Main file name (for zip_release)
render_readme	bool	No	Render the README in the HACS info panel
country	string/array	No	ISO country codes (e.g., "US" or ["US", "CA"])
hide_default_branch	bool	No	Hide default branch from version list
persistent_directory	string	No	Directory to preserve during updates