Home Assistant Community Apps Repository Updater
About
Keeps a Home Assistant apps repository up to date with the apps it lists, fully automated. For every app, it finds the newest version the repository's channel may publish, copies the app's configuration, static files and changelog into the apps repository, renders the READMEs from their templates, and commits the result. One commit per app, straight through the GitHub API, without cloning anything.
It powers the Home Assistant Community Apps project, and runs as a command line tool, a container image and a GitHub Action.
Please note, this program cannot be used with the general documented Home Assistant app repository approach and only works in the setup where each app has its own GitHub repository.
Installation
The Repository Updater needs Python 3.12 or newer. Install it with pip, or run it straight away with uv:
pip install repository-updater
uvx repository-updater --help
It is also available as a container image and as a GitHub Action, see below.
The token
The Repository Updater needs a GitHub token that may commit to the apps
repository. A fine-grained personal access token needs read and write access
to the contents of the apps repository; a classic one needs the repo scope.
Public app repositories need nothing extra; private ones need read access to
their contents as well. To get a token, see the GitHub article:
Create a token.
The commits are made in the name of the account the token belongs to. When that account keeps its email address private, the commits use its GitHub noreply address.
Usage
The Repository Updater is a pretty simple, straightforward CLI tool.
Usage: repository-updater [OPTIONS]
Bring a Home Assistant Apps repository up to date with its apps.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ * --token TOKEN GitHub access token. │
│ [env var: INPUT_TOKEN, GITHUB_TOKEN] │
│ [required] │
│ * --repository OWNER/NAME The Home Assistant Apps repository to update. │
│ [env var: INPUT_REPOSITORY, GITHUB_REPOSITORY] │
│ [required] │
│ --app,--addon APP Update a single app. --addon is the deprecated │
│ name. │
│ [env var: INPUT_APP, INPUT_ADDON] │
│ --force Update apps even when they look up to date. │
│ [env var: INPUT_FORCE] │
│ --dry-run Show what would be committed, without committing. │
│ [env var: INPUT_DRY_RUN] │
│ --cache --no-cache Remember what the apps repository holds, to skip │
│ reloading it. │
│ [env var: INPUT_CACHE] │
│ [default: cache] │
│ --cache-dir PATH Where the cache lives. Defaults to │
│ ~/.cache/repository-updater. │
│ [env var: INPUT_CACHE_DIR] │
│ --version Show the version and exit. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
Every option can also be set through the environment variables listed with
it. When more than one is set, the first one that is not empty wins, and an
option on the command line always beats the environment. --addon and the
INPUT_ADDON variable are deprecated; use --app and INPUT_APP instead.
The cache
A run for a single app still needs every other app, to render the README of
the apps repository. The Repository Updater remembers what the apps repository
holds of each app in a cache, so the next run only loads what changed. Every
cached app is checked against the apps repository first: an app whose
configuration changed since, even by hand, simply gets loaded again. The
cache does keep an app's repository URL and the commit behind its version
until that configuration changes; after renaming an app repository or moving
a release tag, run once with --no-cache. The cache lives in
~/.cache/repository-updater (or $XDG_CACHE_HOME/repository-updater); --cache-dir puts it
elsewhere and --no-cache runs without it.
Using Docker
The Repository Updater is also published as a container image on the GitHub Container Registry, for amd64 and arm64. This allows for quick use without a Python setup, for example on a CI server.
docker run --rm -e GITHUB_TOKEN ghcr.io/hassio-addons/repository-updater:3.0.0 \
--repository hassio-addons/repository
All the options from the previous chapter apply, including their environment variables. For example, this shows the current version:
docker run --rm ghcr.io/hassio-addons/repository-updater:3.0.0 --version
Images are only tagged with their exact version; there is no latest, and
no tag moves along with a new release. Every image is signed with
cosign and carries a build provenance attestation, which can be
checked with:
gh attestation verify --owner hassio-addons \
oci://ghcr.io/hassio-addons/repository-updater:3.0.0
Using a GitHub Action
The Repository Updater is also available as a GitHub Action.
---
name: Repository Update
on:
repository_dispatch:
types: ["update"]
# The token below does the work; the workflow's own token needs nothing.
permissions: {}
jobs:
update:
name: Running updater for ${{ github.event.client_payload.app }}
runs-on: ubuntu-latest
# One run at a time: a run that finds the apps repository changed under
# it stops instead of committing, so queue them up.
concurrency:
group: repository-updater
cancel-in-progress: false
steps:
- name: 🚀 Run Repository Updater
uses: hassio-addons/repository-updater@v3.0.0
with:
app: ${{ github.event.client_payload.app }}
repository: ${{ github.repository }}
token: ${{ secrets.UPDATER_TOKEN }}
Releases are immutable: once published, a version tag can never point anywhere else. Pinning the action to a version, like above, is therefore safe. Pinning it to the full commit SHA of that version is safer still, and what we recommend; Renovate and Dependabot keep such a pin up to date:
uses: hassio-addons/repository-updater@<full commit SHA> # v3.0.0
There are no tags like v3 that move along with every release.
The action takes these inputs:
| Input | Default | What it does |
|---|---|---|
token |
GitHub token that may commit to the apps repository. Required. | |
repository |
The repository it runs in | The apps repository to update. |
app |
Update a single app. addon is the deprecated name for it. |
|
force |
false |
Update apps even when they look up to date. |
dry_run |
false |
Show what would be committed, without committing. |
cache |
true |
Keep the cache between runs with actions/cache. |
Every app gets its own group in the log, and an app that fails shows up as an error annotation on the run, while the other apps carry on.
Once that workflow is in place, from an app repository, you can trigger the above workflow to run. This can be done by dispatching a signal to the updater workflow:
publish:
name: 📢 Publish App
runs-on: ubuntu-latest
steps:
- name: 🚀 Dispatch Repository Updater update signal
uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
with:
token: ${{ secrets.DISPATCH_TOKEN }}
repository: hassio-addons/repository
event-type: update
client-payload: '{"app": "my-app"}'
Apps Repository Configuration
In order for the Repository Updater to do its job, we need to feed it some information. It needs to know which apps there are currently in the apps repository and where each app is located on GitHub.
Secondly, it needs to know the stability channel of the apps repository. There are 3 stability channel levels available:
- stable: Stable releases
- beta: Beta / test releases
- edge: Latest builds, usually built straight from development
Create a .apps.yml file in the root of the apps repository,
which looks like this:
channel: edge
apps:
example:
repository: hassio-addons/app-example
target: example
image: ghcr.io/hassio-addons/example
another:
repository: hassio-addons/app-another
target: homebridge
image: ghcr.io/hassio-addons/another
demo:
repository: hassio-addons/app-demo
target: src
image: ghcr.io/hassio-addons/demo/{arch}
Older apps repositories call this file .addons.yml or .hassio-addons.yml,
and the apps key addons; both still work.
The target in the apps repository is specified as the key for each app,
this will be the directory name inside the apps repository as well. This is
different from the target key, in a way that that key specifies the app
target directory inside the git repository of the app itself.
In the above example, demo will be the name of the app directory
inside the apps repository, while src is the directory in the app
git repo that contains the actual app.
repository specified the location of the app on GitHub. This must be
in organization/repository or username/repository format.
Finally, the image key defines the container image of this app, on the
GitHub Container Registry or any other registry. For an image per
architecture, {arch} is the placeholder for the architecture; a
multi-architecture image needs none.
By default, each release replaces the app's CHANGELOG.md with its release
notes. Set changelog: prepend at the top level of .apps.yml to keep the
earlier entries instead:
channel: stable
changelog: prepend
apps: ...
Each release then adds its notes under a ## <version> heading above the
newest version in CHANGELOG.md. A title like # Changelog and any
introduction stay on top. When an apps repository switches from replace, the
release notes already in CHANGELOG.md get a heading with the version they
belong to. Home Assistant uses these headings to show the changes between the
installed and the new version. Edge updates without a release still replace the
file.
Apps Repository README template
It is nice to have an up to date README.md file in your apps repository,
but maintaining one, can be quite time-consuming. The Repository updater is
able to update the README.md file for you each run.
This is done using a Jinja2 template. Simply create a file called .README.j2
in the root of your apps repository. Most information is collected
from the configuration file of each app (config.yaml, config.yml or
config.json) and its GitHub repository. An app can have a .README.j2 of
its own as well, which gets the variables of that one app.
The following variables are available in your templates and are passed into it upon rendering your template.
- apps: A list of apps in this apps repository, sorted by name
- addons: Alias for
apps(for backward compatibility) - channel: The channel type of this apps repository
- description: The GitHub apps repository description
- homepage: The GitHub apps repository specified homepage URL
- issues: The URL to the issues listing of the GitHub apps repository
- name: The full GitHub name, like
hassio-addons/repository - repo: The full URL to the GitHub apps repository
In the above variables, a list of apps was specified. Each item in this
list contains the following variables:
- name: Name of the app
- description: Description of the app
- url: URL of the app
- repo: URL to the app GitHub repo
- repo_slug: app GitHub slug (:user/:repo)
- archs: List of supported architectures by this app
- slug: The app slug
- target: The target directory of the app inside the apps repository
- image: The container image, as written in
.apps.yml - images: Dictionary of the image per architecture the app supports, like
aarch64andamd64. An app that declares no architectures getsaarch64,amd64,armhf,armv7andi386. - channel: The channel of the apps repository
- version: The version of the app, like
v1.2.3for a release, or the short SHA of a commit on edge - commit: Full SHA of the commit bound to the current version
- date: Date and time of the commit of the version
Examples
It is quite a complex setup to create an example for in this little document.
Nevertheless, see the Home Assistant Community Apps Repository
for an example of .README.j2 and .apps.yml files.
The community project runs the Repository Updater from GitHub Actions. When
an app gets a release, or a new commit on edge, its repository sends an
update event to the apps repositories, whose workflow runs this action for
that one app. See the shared workflows for the whole setup.
Why do this all
Let me start by saying, there is nothing wrong with the documented way of setting up a Home Assistant apps repository. If you are just starting out developing apps, please use the official documented way. You can always decide to change your workflow.
Nevertheless, there are some advantages using the alternative method:
- Each app has its own Git repository, which allows for a maximum separation of concerns. Each app has its own issue list, releases, and all other GitHub goodness.
- Release and versioning is based on GitHub Releases / Git tagging. Which does not need updating of configuration files and is done in one go.
- Each app Git repository is downloadable and instantly buildable locally.
- Every single piece of manual labor around maintaining an apps repository is fully automated. Building, testing, quality control, publishing, changelogs and even the apps repository README are updated automatically. This level of automation allows us to focus completely on developing the actual app.
- Availability of Beta and Edge channels for everyone who's interested or willing to test.
Known issues and limitations
- It only works with apps repositories and app repositories on GitHub.
- A README template renders from a single file;
{% include %}of other files in the repository is not available.
Development
This is a uv project that also uses Node.js for Prettier, with prek running the checks. Set up and run everything with:
npm install
uv sync --group dev
uv run prek run --all-files
uv run pytest runs just the tests. --dry-run, together with --force,
shows what a run would change in a real apps repository without writing
anything. AGENTS.md has more on how the code is laid out.
Changelog & Releases
This repository keeps a change log using GitHub's releases functionality. Releases are immutable: once published, a release and its tag never change, and its package and image carry provenance attestations.
Releases are based on Semantic Versioning, and use the format
of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented
based on the following:
MAJOR: Incompatible or major changes.MINOR: Backwards-compatible new features and enhancements.PATCH: Backwards-compatible bugfixes and package updates.
Support
Got questions?
You have several options to get them answered:
- The Home Assistant Community Forum.
- The Home Assistant Discord Chat Server for general Home Assistant discussions and questions.
- Join the Reddit subreddit in /r/homeassistant
You could also open an issue here on GitHub.
Contributing
This is an active open-source project. We are always open to people who want to use the code or contribute to it.
We have set up a separate document containing our contribution guidelines. Using AI tools to help? Read our AI policy first. Found a security issue? Please follow our security policy instead of opening an issue.
Thank you for being involved! 😍
Authors & contributors
The original setup of this repository is by Franck Nijhof.
For a full list of all authors and contributors, check the contributor's page.
We have got some Home Assistant apps for you
Want some more functionality to your Home Assistant instance?
We have created multiple apps for Home Assistant. For a full list, check out our GitHub Repository.
License
MIT License
Copyright (c) 2018-2026 Franck Nijhof
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Metadata
Release files for repository-updater 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| repository_updater-3.0.0.tar.gz | 35.2 kB | With provenance | Details for repository_updater-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| repository_updater-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for repository_updater-3.0.0-py3-none-any.whl |
Total release size: 77.5 kB
Release files / repository_updater-3.0.0.tar.gz
| Download URL | repository_updater-3.0.0.tar.gz |
|---|---|
| Size | 35.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0011f9eaddab4e1efcaab2530ec8468ac15f64818d4022892d22e8a7733ddef6
|
|
BLAKE2b-256 checksum How to use checksums |
6f87f7e303a11469bb4efe519b796854883fd04272ab34b262c2515f5ee797c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logRelease files / repository_updater-3.0.0-py3-none-any.whl
| Download URL | repository_updater-3.0.0-py3-none-any.whl |
|---|---|
| Size | 42.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6e1201357d6f1c73783c85a439182f4093d7a693a09d7e4433cb69472667d806
|
|
BLAKE2b-256 checksum How to use checksums |
8b57ec8889dcc9158fa9dc901b30d51883b7afc3ef69695fa074e62266d97df9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logSecurity for repository-updater 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for repository_updater-3.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.