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 |

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