Skip to content

Publishing Guide

Jump to bottom
L3DigitalNet edited this page Feb 7, 2026 · 1 revision

Publishing Guide

Guide to publishing your Home Assistant integration to HACS (Home Assistant Community Store).

What is HACS?

HACS is the Home Assistant Community Store - the primary distribution channel for custom integrations.

Benefits:

  • Easy installation for users (one-click install)
  • Automatic updates
  • Larger audience reach
  • Integration validation
  • Community trust

Prerequisites

Before submitting to HACS:

1. Quality Requirements

Minimum: Bronze tier (see Quality Scale Guide)

  • ✅ Config flow implemented
  • ✅ Automated tests
  • ✅ Linting passes
  • ✅ Proper manifest.json

Recommended: Silver/Gold tier for better user experience

2. Repository Requirements

  • ✅ Public GitHub repository
  • ✅ Proper LICENSE file (MIT, Apache 2.0, GPL-3.0, etc.)
  • ✅ README.md with clear documentation
  • ✅ Semantic versioning (tags/releases)
  • ✅ Working integration (not broken)

3. Documentation Requirements

README.md must include:

  • What the integration does
  • How to install (via HACS)
  • How to configure
  • Troubleshooting section
  • Link to issue tracker

Repository Structure

Your repository should look like this:

your-integration/
├── custom_components/
│   └── your_integration/
│       ├── __init__.py
│       ├── manifest.json
│       ├── config_flow.py
│       ├── coordinator.py
│       ├── const.py
│       ├── sensor.py
│       ├── strings.json
│       └── translations/
│           └── en.json
├── .github/
│   └── workflows/
│       └── validate.yml
├── tests/
│   └── ... (your tests)
├── README.md
├── LICENSE
├── hacs.json
└── .gitignore

Key points:

  • Integration code MUST be in custom_components/your_integration/
  • NO other directories at root (like config/, www/, etc.)
  • HACS will install the entire custom_components directory

Creating hacs.json

Create hacs.json in repository root:

{
  "name": "Your Integration",
  "content_in_root": false,
  "homeassistant": "2024.4.0",
  "render_readme": true,
  "country": ["US"]
}

Fields:

  • name: Display name in HACS
  • content_in_root: Always false (content is in custom_components/)
  • homeassistant: Minimum HA version required
  • render_readme: Show README in HACS
  • country: ISO country codes (optional, for region-specific integrations)

Version Management

Semantic Versioning

Use MAJOR.MINOR.PATCH format:

  • MAJOR: Breaking changes (config schema changes, removed features)
  • MINOR: New features (backward-compatible)
  • PATCH: Bug fixes (backward-compatible)

Examples:

  • 1.0.0 - Initial release
  • 1.1.0 - Add new sensor platform
  • 1.1.1 - Fix temperature sensor bug
  • 2.0.0 - Change config flow (breaking)

Update manifest.json

REQUIRED: Update version in manifest.json:

{
  "domain": "your_integration",
  "name": "Your Integration",
  "version": "1.1.0",
  ...
}

HACS requires this field! Without it, submission will be rejected.

Create GitHub Release

# Tag the release
git tag v1.0.0
git push origin v1.0.0

# Or create release via GitHub UI:
# Releases → Draft new release → Create tag → Publish

Release notes should include:

  • What's new
  • Bug fixes
  • Breaking changes (if any)
  • Upgrade instructions (if needed)

HACS Validation

Before submitting, validate your integration:

1. Run HACS Action (Recommended)

Add to .github/workflows/validate.yml:

name: Validate

on:
  push:
  pull_request:
  schedule:
    - cron: "0 0 * * *"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: HACS validation
        uses: hacs/action@main
        with:
          category: integration

This validates:

  • ✅ Repository structure
  • ✅ hacs.json format
  • ✅ manifest.json version field
  • ✅ Required files exist

2. Manual Checks

# Check structure
ls custom_components/your_integration/manifest.json  # Should exist

# Verify manifest has version
grep "version" custom_components/your_integration/manifest.json

# Verify hacs.json is valid JSON
python -m json.tool hacs.json

# Verify README exists
ls README.md

Submission Process

1. Prepare Repository

  • Create public GitHub repository
  • Add LICENSE file
  • Create comprehensive README.md
  • Add hacs.json
  • Update manifest.json with version
  • Create v1.0.0 release
  • Ensure HACS validation passes

2. Submit to HACS

Visit: https://github.com/hacs/default/blob/master/README.md

Follow instructions to:

  1. Fork the hacs/default repository
  2. Add your repository to the appropriate JSON file
  3. Create pull request

PR format:

Add integration: Your Integration

Repository: https://github.com/username/your-integration
Type: integration
Category: integration

3. Wait for Review

Review process:

  • HACS maintainers will review your PR
  • Validation checks must pass
  • May request changes
  • Usually takes 1-7 days

Common rejection reasons:

  • Missing version in manifest.json
  • Invalid hacs.json format
  • Broken integration
  • Missing documentation
  • License issues
  • Duplicate/similar existing integration

4. After Approval

Once merged:

  • ✅ Integration appears in HACS
  • ✅ Users can install via HACS UI
  • ✅ Updates are automatic

Updating Your Integration

Release New Version

  1. Make changes
  2. Update manifest.json version: 
    "version": "1.1.0"
  3. Commit and push
  4. Create new release: 
    git tag v1.1.0
git push origin v1.1.0
  5. Users get update notification in HACS

No need to submit PR again! HACS automatically detects new releases.

Best Practices

Documentation

README.md should include:

# Your Integration

## Installation

### HACS (Recommended)
1. Open HACS
2. Go to Integrations
3. Search for "Your Integration"
4. Click Install

### Manual
1. Copy `custom_components/your_integration` to `<config>/custom_components/`
2. Restart Home Assistant

## Configuration

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for "Your Integration"
4. Follow setup wizard

## Features

- List features
- Be specific

## Troubleshooting

Common issues and solutions

## Support

- [Report Issues](https://github.com/username/repo/issues)
- [Discussions](https://github.com/username/repo/discussions)

Changelog

Maintain CHANGELOG.md:

# Changelog

## [1.1.0] - 2026-02-07
### Added
- New humidity sensor

### Fixed
- Temperature sensor precision

## [1.0.0] - 2026-02-01
- Initial release

Breaking Changes

If introducing breaking changes:

  1. Bump MAJOR version (e.g., 1.9.0 → 2.0.0)
  2. Document migration in README and release notes
  3. Provide migration guide if config schema changes
  4. Consider deprecation period (warn in 1.9.0, break in 2.0.0)

Common Issues

"Repository structure is not compliant"

Cause: Integration not in custom_components/

Fix:

# Move files to correct location
mkdir -p custom_components/your_integration
mv *.py custom_components/your_integration/

"Missing version in manifest.json"

Cause: No version field

Fix:

{
  "domain": "your_integration",
  "version": "1.0.0",
  ...
}

"No releases found"

Cause: No GitHub releases created

Fix:

git tag v1.0.0
git push origin v1.0.0

Resources

Next Steps

After publishing:

  • Monitor issues and provide support
  • Release updates regularly
  • Engage with users in Discussions
  • Consider submitting to HA Core (if applicable)

Related Guides

Clone this wiki locally