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

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