I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons

If this add-on saves you time or makes your setup easier, I would be very grateful for your support!

Addon informations

Thanks to everyone having starred my repo! To star it click on the image below, then it will be on top right. Thanks!

About

This script allows to automatically update addons based on upstream new releases. This is only an helper tool for developers. End users don’t need that to update their addons - they are automatically alerted by HA when an update is available

Installation

The installation of this add-on is pretty straightforward and not different in comparison to installing any other Hass.io add-on.

Add my add-ons repository to your home assistant instance (in supervisor addons store at top right, or click button below if you have configured my HA)
Install this add-on.
Configure the add-on to your preferences, see below
Click the Save button to store your configuration.
Start the add-on.
Check the logs of the add-on to see if everything went well.

Configuration

No webUI. Configuration is set in 2 ways.

Updater.json

In the addon folder of your repository (where is located you config.json), create a "updater.json" file. This file will be used by the addon to fetch the addon upstream informations. Only addons with an updater.json file will be updated. Here is an example.

You can add the following tags in the file :

github_fulltag: true is for example "v3.0.1-ls67" false is "3.0.1"
github_beta: true/false ; should it look only for releases or prereleases ok
github_havingasset : true if there is a requirement that a release has binaries and not just source
github_tagfilter: filter a text in the release name
github_exclude: exclude a text in the release name
last_update: automatically populated, date of last upstream update
repository: 'name/repo' coming from github
paused: true # Pauses the updates
slug: the slug name from your addon
source: container/dockerhub/github,gitlab,bitbucket,pip,hg,sf,website-feed,local,helm_chart,wiki,system,wp,codeberg (Codeberg is supported via its Gitea API, which is configured automatically)
upstream_repo: name/repo, example is 'linuxserver/docker-emby'. With source: container it is instead a full image reference, example is 'ghcr.io/imagegenius/immich:3'
upstream_version: automatically populated, corresponds to the current upstream version referenced in the addon
dockerhub_by_date: in dockerhub, uses the last_update date instead of the version
dockerhub_list_size: in dockerhub, how many containers to consider for latest version

Addons built on someone else's image

An addon that does not build the application itself, but builds FROM an image a third party publishes, must publish the version that image holds and not the newest release of the application. ghcr.io/imagegenius/immich:3 is a rebuild of immich lagging its upstream by days to weeks: tracking immich-app/immich published a version the addon did not contain, and left the addon with no reason to rebuild once the image finally caught up.

source: container reads the version out of the image itself. Set upstream_repo to the exact image reference used in build.json, tag included:

{
  "source": "container",
  "upstream_repo": "ghcr.io/imagegenius/immich:3"
}

The version comes from the image's org.opencontainers.image.version label, read from the first linux image the tag publishes, and the addon is left alone when there is no label to read. Written against ghcr.io, which serves anonymous pull tokens from https://ghcr.io/token; a registry authenticating differently, such as Docker Hub, yields no version and the addon is skipped.

The manifest digest is recorded next to the version, in upstream_digest, and the addon is rebuilt when either of the two moves. A publisher rebuilding the same version, for a base image security fix or a packaging revision, repoints the tag at new content under an unchanged label, and the digest is the only thing that says so. upstream_digest is populated automatically; seed it by hand when migrating an addon to this source, or the first run counts the unknown digest as a change and rebuilds once for nothing.

The label is metadata the publisher chooses. Some images carry none, and some record their own packaging revision rather than the application version, so this source is opt-in per addon and never a default.

Addon version numbering

The version written in the addon config.yaml is the one Home Assistant compares to decide whether an update is available. Home Assistant hides the update when it can order both versions and the new one is not strictly newer (1.2.3 -> 1.2.3-2 is a semver pre-release, so it is older), and it cannot order tags such as version-bf9e0b4f or ubuntu-2026-06-01 at all.

The addon version is therefore derived from the upstream tag:

a tag Home Assistant can order and that is newer is used as it is
1.2.3-4 and 1.2.3+4 become 1.2.3.4
a pre-release marker becomes a section of its own, so the number it carries keeps ordering the addon: 5.0.0b5 -> 5.0.0.5
a tag it cannot order keeps every number it carries, in order: v26.2-ls256 -> v26.2.256, nightly-2.6.1.5509-ls8 -> 2.6.1.5509.8, 4.16-r0-ls94 -> 4.16.0.94, ubuntu-2026-07-28 -> 2026.07.28. Words holding no number, an architecture, and anything else such as a commit hash are left out
a tag holding no number at all (version-bf9e0b4f, sts) increments the current addon version (1.37 -> 1.38), or uses the date when there is nothing to increment (2026.08.01, then 2026.08.01.1 for a second update the same day)

updater.json always keeps the raw upstream tag, so the next run still compares upstream with upstream and a single upstream release never triggers two addon updates. The raw tag is also kept in the Dockerfile and the build files, and is added to the changelog entry when it differs from the addon version.

These rules are checked by python3 /usr/bin/ha_version.py --selftest, which can be run from a terminal in the addon container.

Addon configuration

Here you define the values that will allow the addon to connect to your repository.

repository: 'name/repo' coming from github
gituser: your github username
gitapi: your github api token(classic) https://github.com/settings/tokens
gitmail: your github email
date_iso8601: true # use ISO8601 dates (YYYY-MM-DD) instead of DD-MM-YYYY
verbose: 'false'

Example:

repository: alexbelgium/hassio-addons
gituser: your github username
gitapi: your github api token
gitmail: your github email
date_iso8601: true
verbose: "false"

Custom Scripts and Environment Variables

This addon supports custom scripts and environment variables through the app_config mapping:

Custom scripts: See Running Custom Scripts in Addons
Environment variables: Use the add-on env_vars option and see Add Environment Variables to your Addon for details.

README.md Unescape Escape

Home assistant add-on: addons updater