Marketplace Refresh

Features

• Check for updates button and marketplace_refresh.check_updates action: the catalog is read again, then every installed repository is fetched again from GitHub (with a GitHub account connected to the Marketplace), four at a time, and the Marketplace's update entities are refreshed
• marketplace_refresh.check_repository action: checks only the repositories behind the Marketplace update entities you give, and waits for the result
• GitHub rate limit: before a check, Marketplace Refresh reads the requests left (free) and doesn't start a check that would bring them under the Marketplace's own reserve (1,000, about 10 per repository): it would stop halfway with the Marketplace disabled until the limit resets. The check is tried again a minute after the reset; check_repository is refused the same way
• marketplace_refresh.install_updates action and Update all button on the card: installs every update available (or the ones you give), one after the other, administrators only; a failed install is tried again twice (after 30 s, then 90 s) — GitHub sometimes fails to serve one of a release's files — unless the Marketplace is disabled meanwhile; optionally after a Home Assistant backup, and nothing is installed if the backup fails
• Automatic check at the interval set in the integration options (24 hours by default, 0 to turn it off), counted from the last check and kept across restarts: an overdue check runs as soon as Home Assistant has started, and a check that failed (or couldn't start) is tried again within the hour
• marketplace_refresh_updates_found event when a check finds updates that the previous one didn't, for notifications and automations
• Diagnostics to download from the integration page, secrets redacted
• Status sensor (idle, running, error) with the progress (done / total), the number of updates found and the repositories that failed
• Last check sensor (timestamp), with the check interval and when the next automatic check is due
• Lovelace card bundled with the integration: status and progress, last and next check, the updates available and the repositories that couldn't be checked
• One failing repository doesn't stop the others; a check never runs twice at the same time, and check_repository waits for a full check that is running instead of starting a second one
• Also used by the System Monitor Card for its Marketplace section
• English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek (pt-BR uses the European Portuguese texts)

Prerequisites

• Home Assistant 2026.11 or later (the Marketplace comes with it; on 2026.10 and older, use HACS Refresh 1.0.x, the previous name of this project, with HACS)
• A GitHub account connected to the Marketplace to check the repositories from GitHub; without one, a check only reads the catalog and the repositories added from a link can't be checked (see How it works)
• The Check for updates button is open to every user: it only fetches information, like the Marketplace's own refresh, and never starts a second check while one runs. The actions marketplace_refresh.check_updates and marketplace_refresh.check_repository are for administrators only (automations and scripts run without a user and can still call them): each call asks GitHub again and spends the Marketplace's rate limit. marketplace_refresh.install_updates installs code on the server and is for administrators only too, like the Marketplace itself; it also needs the Marketplace warning to have been accepted once in Settings → Marketplace

Configuration

Settings → Devices & services → Add integration → Marketplace Refresh, then choose the check interval. Change it later with the Configure button.

Entities#

Action marketplace_refresh.check_updates#

Check every night and get notified of the updates found:

triggers:
  - trigger: time
    at: "04:00:00"
actions:
  - action: marketplace_refresh.check_updates
    data:
      wait: true
  - condition: template
    value_template: "{{ state_attr('sensor.marketplace_refresh_status', 'updates') | int(0) > 0 }}"
  - action: notify.mobile_app_phone
    data:
      message: "{{ state_attr('sensor.marketplace_refresh_status', 'updates') }} Marketplace update(s) available"

Action marketplace_refresh.check_repository#

The action ends once the repositories are checked, and fails with the reason if one could not be. It doesn't change the status or the last check, which belong to the full check. While a full check runs, it waits for that check to end and fails if that check failed or could not check one of these repositories; a repository already being checked by another call is not checked twice: the action waits for that call's result, and checks it itself if that call is cancelled first. A full check started meanwhile waits for these repositories too instead of checking them again. If Marketplace Refresh is reloaded or removed while the action waits (here or with wait: true), it fails with "The check was cancelled".

action: marketplace_refresh.check_repository
data:
  entity_id: update.mushroom_update

Action marketplace_refresh.install_updates#

Installs the updates one after the other with update.install, in the background (a check running ends first). One failing update doesn't stop the others; the failures are in the status sensor's install_failed attribute. Administrators only, like the Marketplace, and the Marketplace warning must have been accepted once in Settings → Marketplace (an install from an automation runs without a user); it can't run twice at the same time. Meanwhile, no full check starts: the Check for updates button is greyed out, marketplace_refresh.check_updates fails with "Updates are being installed", and an automatic check that falls due runs once the installs are done. Integrations need a restart of Home Assistant afterwards, which the Marketplace asks for in Settings → Repairs.

action: marketplace_refresh.install_updates
data:
  wait: true

Event marketplace_refresh_updates_found#

Fired at the end of a full check (button, check_updates or automatic) when updates are available that the previous full check didn't find: only when the set of repositories with an update grows, not when it stays the same or shrinks (an update installed, then found again later, fires again). The first check after installing the integration only records the updates available; the list is kept across restarts. check_repository doesn't fire it.

triggers:
  - trigger: event
    event_type: marketplace_refresh_updates_found
actions:
  - action: notify.mobile_app_phone
    data:
      title: "Marketplace"
      message: >-
        {{ trigger.event.data.count }} new update(s): {{ trigger.event.data.updates | join(', ') }}
        ({{ trigger.event.data.total }} available)

Card

The integration serves the Marketplace Refresh Card and adds it to the dashboard resources (or loads it on every page when the resources are managed in YAML): no separate install. Add it from the card picker, or:

type: custom:marketplace-refresh-card

• Header: status (up to date, n updates, n failed, checking done/total, error), when the last check ran and when the next automatic one is due, and the Check for updates button
• Progress bar while a check runs
• Few GitHub requests left: under 1,500, a line with the number left and when GitHub's limit resets — checks wait for it
• Updates available (with their number): the repositories with an update, from the Marketplace's own update entities, with the installed and new version, hidden when there is none. A row opens the update entity, to install it or read the release notes
• Update all (n): installs every update listed, one after the other, after a confirmation at the top of the card (administrators only). The rows being installed and the number left show the progress
• Could not be installed: the updates that failed, with the error
• Could not be checked: the repositories the last check couldn't fetch (and, without a GitHub account connected, the ones added from a link, with a line saying why), and the error of a check that failed

Every option is in the visual editor:

The System Monitor Card also shows the Marketplace extensions with their update status, and its Check for updates button presses this integration's button.

How it works

The Marketplace has no action to check everything: its panel refreshes one repository at a time over its websocket API. A full check here:

1. reads the catalog again, as the Marketplace does every 6 hours: one request per content type, no GitHub API call, and it carries the latest version of every catalog repository;
2. with a GitHub account connected to the Marketplace, does for every installed repository what the Marketplace's marketplace/repository/refresh command does for one: it asks the repository to update its information from GitHub, four at a time, saves the Marketplace's data, then tells its update entities to refresh.

The update entities (update.* of platform marketplace) then show the new latest versions, like after a manual refresh in the Marketplace.

Without a GitHub account connected, the Marketplace runs on GitHub's anonymous limit (60 requests an hour), far too small to fetch every repository: a check then only reads the catalog, and the repositories added from a link, which the catalog doesn't list, are reported as "could not be checked" (the status sensor's not_checked attribute, not a failure of check_updates). check_repository always asks GitHub, as the Marketplace's own refresh does, also during a full check for these repositories.

This relies on the Marketplace manager (the runtime_data of its config entry), as the Marketplace's own websocket commands do. The integration checks that the attributes it needs exist: if a future Home Assistant version changes them, the action fails with a clear message instead of breaking Home Assistant.

Checks go through the Marketplace's GitHub client, so they count towards its GitHub API rate limit (5,000 requests per hour with a connected account).

To report a problem, download the diagnostics from Settings → Devices & services → Marketplace Refresh → ⋮ → Download diagnostics: the options, the last check (status, updates, failures, installs) and the Marketplace's state, with tokens, passwords, usernames and URLs redacted.

To debug:

logger:
  logs:
    custom_components.marketplace_refresh: debug

Support

If you find this project useful, you can support its development:

Deprecated

• Marketplace Refresh is now a module of System Hub, and this repository is archived: no more updates here. Turned on in System Hub, the module takes over the settings of Marketplace Refresh. While both are set up, Marketplace Refresh raises a repair in Settings → Repairs, as it would otherwise run twice and register its cards twice: remove Marketplace Refresh and its card resource once the module is on. See Migrating (juju35/ha-system-hub#49, thanks @FredM67).

Improvements

• Card: with few GitHub requests left (under 1,500, as read at the last check), a line says how many and when the limit resets — the checks wait for it. Gone once it has reset.

Features

• GitHub rate limit: before a check, the requests left are read (that request is free). A check that would bring them under the Marketplace's reserve (1,000 left; about 10 per repository) is not started — it would stop halfway, the Marketplace disabling itself until the limit resets — and fails with the requests left and needed and the reset time; the next one runs a minute after the reset instead of an hour later. check_repository is refused the same way. The status sensor shows rate_limit_remaining and rate_limit_reset (not recorded). Without a GitHub account, or when the limit can't be read, checks run as before.

Features

• Install retries: an update that fails to install (Update all, install_updates) is tried again twice, after 30 s then 90 s, before being listed as failed. GitHub sometimes answers 500 on one of a release's files — a card with its translations split out downloads 22 — and the whole install fails; a little later the same download goes through. No retry once the Marketplace is disabled (rate limit), nor when the update was installed or skipped meanwhile.

Maintenance

• No code change: released again to check the installation from the Marketplace.

Features

• Back up before installing updates (option, off by default): Update all first creates Home Assistant's automatic backup (backup.create_automatic, with the settings of Settings → System → Backups), and installs nothing if it fails; the failure is listed with the updates that couldn't be installed. marketplace_refresh.install_updates gets a backup field to ask for it or not, whatever the option.