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)
• codeowners — At least one GitHub username
• documentation — URL to docs
• issue_tracker — URL for bug reports

hacs.json Configuration

Create hacs.json in repository root:

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

All hacs.json Options

Key	Type	Required	Description
name	string	Yes	Display name in HACS
homeassistant	string	No	Minimum HA version (e.g., "2024.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)
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

Validation Checklist

Before submitting to HACS default repository:

• manifest.json has all required fields including issue_tracker
• hacs.json exists with at least name field
• README.md exists with installation instructions
• Repository has description and topics on GitHub
• At least one GitHub Release published (tag must match manifest version)
• HACS validation action passes
• Hassfest validation passes

Troubleshooting

"Invalid manifest" — Check JSON syntax; ensure all required fields present; version must be valid semver.

"Missing hacs.json" — File must be in repository root (not in custom_components).

"No release found" — Publish a GitHub Release (not just a tag); release tag should match manifest version.

Related Skills

• HACS publishing workflow → ha-hacs-publishing
• Integration structure → ha-integration-scaffold