Tracking HACS download counts per release

[svasek]

Tracking HACS download counts per release

Hi @AJediIAm, @rhammen,

I'd like to suggest switching the release process to use zip release assets instead of relying on GitHub's auto-generated source code archives.

Problem

Currently, when HACS installs this integration, it downloads the auto-generated source code archive (the "Source code (zip)" that GitHub creates automatically for every release). The issue is that GitHub API does not expose download counts for these auto-generated archives — the download_count field is only available for explicitly uploaded release assets (via the Release Assets API).

This means there's no way to see how many users have installed each specific release through HACS or via the GitHub API.

Solution

By switching to a zip release asset workflow, each release would have an explicitly uploaded .zip file. HACS would then download this asset instead of the auto-generated source archive, and GitHub would track the download_count for each asset — giving visibility into how many times each release was actually downloaded/installed.

Required changes

1. Update hacs.json — add two keys:

{
    "name": "Luxtronik",
    "render_readme": true,
    "homeassistant": "2025.6.0",
    "filename": "luxtronik.zip",
    "zip_release": true
}

2. Update the release workflow — the CI/CD pipeline needs to create and upload a luxtronik.zip asset containing the custom_components/luxtronik/ directory for each release.

Reference

This is documented in the HACS manifest documentation:

zip_release (bool) — Indicates whether the content is in a zipped archive when releases are published on GitHub. If you use this you also need to add filename. This is only supported for integrations.

As a practical example, I use this approach in my own integration homeassistant-vistapool-modbus, where hacs.json contains:

{
    "name": "VistaPool Modbus Integration (for NeoPool Controllers)",
    "filename": "vistapool_modbus.zip",
    "homeassistant": "2025.1.0",
    "render_readme": true,
    "zip_release": true
}

This has been working well and provides clear download statistics per release.

Benefits

• Download analytics — see how many users installed each release via GitHub API (download_count on each asset)
• Better insight into adoption rate of new versions
• No impact on users — HACS handles zip_release transparently, the installation experience is the same

[AJediIAm]

I'll have a look at it

[AJediIAm]

[svasek]

Hi @AJediIAm and @rhammen,

Just a reminder that the number shows the download count for the latest release.
If you want to see other releases, you need to query the GitHub API.

Example command to get the download count for each release:

curl -sH "Accept: application/vnd.github+json" \
  https://api.github.com/repos/BenPru/luxtronik/releases | \
  jq -r '.[] | .tag_name as $t | [.assets[].download_count] | add | select(. > 0) | "\($t): \(.)"'

If you have GitHub CLI:

gh api repos/BenPru/luxtronik/releases --jq '.[] | .tag_name as $t | [.assets[].download_count] | add | select(. > 0) | "\($t): \(.)"'

[AJediIAm]

I took the screenshots just after I stalling a new latest release. It appears to my that all downloads are shown. We'll see what happens with the number in the next release