QA Dist Manager

[jgab 2,647]

 

QA Dist Manager

A 

Please login or register to see this link.

 QuickApp that lets you install, upgrade, and downgrade other QuickApps directly from GitHub — without leaving the HC3 UI.

---

Features

• Load one or more manifest files from GitHub (or any URL)
• Browse all QuickApps listed in the manifests
• See which versions are already installed on your HC3
• Install a new instance or update an existing one to any release
• Syncs files, UI layout, and interfaces during an update
• Supports per-QA "ignore" lists to preserve user-specific files (e.g. userconfig)
• Multiple manifest sources — just add more manifestXxx QA variables

---

Installation

1. Download the latest .fqa file from the 

   Please login or register to see this link.

    and import it into your HC3.
2. Import it into your HC3 via Settings → QuickApps → Add QuickApp → Import.
3. Open the QuickApp and set the manifestUrl variable to point to your manifest (see below).
4. Optionally set githubToken if you need more than 60 GitHub API requests per hour.

---

QuickApp Variables

Variable	Required	Description
manifestUrl	Yes	URL to a dist.json manifest file. Any variable whose name starts with manifest is loaded — add more for additional sources (e.g. manifestFriend).
githubToken	No	Personal access token for GitHub API. Leave empty for anonymous access (60 req/hour).

Multiple manifest sources

You can load QAs from several publishers at once. Add extra QA variables named with any prefix starting with manifest:

Please login or register to see this code.

All entries are merged. If the same uid appears in multiple manifests, the first one wins.

---

For QA Authors — Publishing Your Own Manifest

To distribute your QuickApps via QA Dist Manager, host a dist.json file in your GitHub repository and share the raw URL.

Manifest schema

Please login or register to see this code.

Field reference

Field	Required	Description
author	Yes	Your name or organisation. Shown in the QA Dist Manager UI.
minVersion	No	Minimum QA Dist Manager version required to use this manifest (e.g. "0.1.2"). If the installed QADist is older, the manifest is skipped with a warning. Omit or leave blank for no restriction.
quickApps	Yes	Array of QuickApp entries.
name	Yes	Display name shown in the selector.
uid	Yes	A stable unique identifier for this QuickApp. Must never change between releases. Used to match already-installed instances on the HC3. Any unique string works — e.g. "UPD896846032517896".
description	No	Short description shown below the selector.
url	Yes	GitHub API base URL for the repository:  Please login or register to see this link.
fqa	Yes	Relative path to the .fqa file inside the repo, e.g. dist/MyApp.fqa. The file is fetched from the raw GitHub URL at the selected release tag.
versionFile	No	Name of the Lua file inside an installed QA that contains the version string. Used to show the current version in the Installed dropdown.
versionPattern	No	Lua string.match pattern used to extract the version from versionFile. Must capture the version string in a capture group. Example: local VERSION = "([^"]+)"
ignore	No	Array of file names to exclude during updates. Files listed here are never overwritten from the FQA and never deleted if they already exist on the device. Use this to preserve user-edited files like userconfig.

Releases and tags

QA Dist Manager fetches the list of available versions by calling the GitHub releases API (/releases). If no releases are found, it falls back to tags (/tags). Publish a GitHub release (or push a tag) for each version you want to make available.

The .fqa file must exist at the tagged commit under the path given in fqa.

How to create a release on GitHub (recommended)

A release is the most visible way to publish a version. It appears on your repo's front page and lets you attach files and release notes.

1. Go to your repository on GitHub.
2. In the right-hand sidebar, click Releases (or go to 

   Please login or register to see this link.

   ).
3. Click Draft a new release.
4. In the Choose a tag field, type a new version string such as v1.0.0 and select Create new tag: v1.0.0 on publish.
5. Fill in a Release title (e.g. Version 1.0.0) and optionally add release notes.
6. Make sure your .fqa file is already committed and pushed to the branch you're releasing from (usually main).
7. Click Publish release.

The tag name becomes the value shown in the Release dropdown inside QA Dist Manager. Use a consistent naming scheme like v1.0.0, v1.1.0, etc.

How to create a tag only (lightweight alternative)

If you prefer not to write release notes, you can push a plain git tag. QA Dist Manager will find it via the tags fallback.

Using the GitHub web UI:

1. Go to your repository → Code tab.
2. Click the branch/tag dropdown (top-left, shows main by default).
3. Type a new tag name such as v1.0.0 in the search box.
4. Click Create tag: v1.0.0 on main (or whatever branch is current).

Using the command line:

Please login or register to see this code.

Versioning convention

It is recommended to use 

Please login or register to see this link.

: vMAJOR.MINOR.PATCH

Part	When to increment
MAJOR	Breaking changes (e.g. removed user-config keys)
MINOR	New features, backwards compatible
PATCH	Bug fixes only

Examples: v1.0.0, v1.2.3, v2.0.0

Generating a UID

A UID is just a string that uniquely identifies your QuickApp. You can use any method:

Please login or register to see this code.

The only requirement is that it stays constant across all releases of the same QuickApp.

Minimal example

Please login or register to see this code.

Host this at 

Please login or register to see this link.

 and share that URL with users.

---

How updates work

When you press Apply with an existing installed instance selected:

1. Downloads the .fqa for the chosen release from GitHub.
2. Compares the file list with what's currently installed.
   • Creates files that are new in the release.
   • Updates content of all non-ignored files.
   • Deletes files that are no longer in the release (unless listed in ignore).
3. Syncs interfaces (adds/removes) based on initialInterfaces in the FQA.
4. Updates the UI layout (uiView, uiCallbacks, viewLayout) on the device.
5. HC3 automatically restarts the QuickApp after file changes.

---

Programmatic API

Other QuickApps can call QA Dist Manager via fibaro.call to install or update QuickApps automatically — for example to self-update on a daily timer.

Because fibaro.call is fire-and-forget, results are delivered asynchronously. Pass callbackId and callbackMethod in the args table; QA Dist Manager will call fibaro.call(callbackId, callbackMethod, result) when finished.

Methods

apiListReleases(args)

Fetch the available releases for a QuickApp.

Arg	Type	Description
uid	string	Required. UID of the QuickApp as listed in the manifest.
refresh	bool	true to force a manifest re-fetch even if the cache is fresh. Default false.
callbackId	number	Device ID of the QuickApp to call back.
callbackMethod	string	Method name to call on the callback device.

Result:

Please login or register to see this code.

apiInstall(args)

Download and install a new instance of a QuickApp.

Arg	Type	Description
uid	string	Required. UID of the QuickApp.
tag	string	Release tag to install. "latest" or omit for the newest release.
refresh	bool	Force manifest re-fetch. Default false.
callbackId	number	Callback device ID.
callbackMethod	string	Callback method name.

Result:

Please login or register to see this code.

apiUpdate(args)

Update an existing installed instance.

When force=false (the default) and the manifest entry has versionFile/versionPattern set, QA Dist Manager reads the running version and skips the update if it already matches the target tag.

Arg	Type	Description
deviceId	number	Required. Device ID of the installed instance.
uid	string	Required. UID of the QuickApp in the manifest.
tag	string	Target release tag. "latest" or omit for the newest release.
force	bool	true to update even if already on the target version. Default false.
refresh	bool	Force manifest re-fetch. Default false.
callbackId	number	Callback device ID.
callbackMethod	string	Callback method name.

Result:

Please login or register to see this code.

Self-updating QuickApp example

Please login or register to see this code.

Note: apiInstall and apiUpdate set an internal busy flag while running. Concurrent calls from different devices will receive { ok=false, msg="busy" } until the current operation finishes.

---

License

MIT

Edited April 7 by jgab

[jgab 2,647]

v1.0.1 of distmanager that allow ignore files contain lua patterns.

[jgab 2,647]

v1.0.3 supports manifest with minimum supported QaDist version.

[Brors94 115]

I downloaded the v1.3 Qa and have not done any changes and tried to install the Ikea Dirigera QA you got listed in your repo and gets this:

 

Please login or register to see this code.

This is also really nice!  
I am trying to setup my own repo, dist.json and manifest to test with and will give you feedback on that to  
 

[jgab 2,647]

Ok, it was my manifest that wasn't in order. Will take some time to get everything in order.
(the Dirigera.fqa was in the wrong place in the repo so we got an 404)
Anyway, checked Dirigera and it deploys now.

1 hour ago, Brors94 said:

This is also really nice!  
I am trying to setup my own repo, dist.json and manifest to test with and will give you feedback on that to  
 

Yes, if you upload the fqa to your repo it's fairly easy to use.
Just remember to set the quickAppUuid property to the uid. It's not 100% clear from the docs.

Edited April 6 by jgab

[Brors94 115]

37 minutes ago, jgab said:

Ok, it was my manifest that wasn't in order. Will take some time to get everything in order.
(the Dirigera.fqa was in the wrong place in the repo so we got an 404)
Anyway, checked Dirigera and it deploys now.

Yes, if you upload the fqa to your repo it's fairly easy to use.
Just remember to set the quickAppUuid property to the uid. It's not 100% clear from the docs.

Now it crashed

 

Please login or register to see this code.

I have added a manifestjbs = https://raw.githubusercontent.com/Brors94/HC3Quickapps/refs/heads/main/dist.json
The file:
 

Please login or register to see this code.

and a token for github.

And it shows the QA name from the dist.json I made in the dropdown menu.

The uid like I have made should be okey? 🤔

Edit:
Also the way I make a Repo for all my Quickapps is okey to I guess?🤔
I see you have diffrent Repos for Diffrent quickapps. But I think it is more managable for myself with 1 repo and folders for each QA  
Hope that is okey? 



 

Edited April 6 by Brors94

[jgab 2,647]

29 minutes ago, Brors94 said:

Now it crashed

 

Please login or register to see this code.

I have added a manifestjbs = https://raw.githubusercontent.com/Brors94/HC3Quickapps/refs/heads/main/dist.json
The file:
 

Please login or register to see this code.

and a token for github.

And it shows the QA name from the dist.json I made in the dropdown menu.

The uid like I have made should be okey? 🤔

Edit:
Also the way I make a Repo for all my Quickapps is okey to I guess?🤔
I see you have diffrent Repos for Diffrent quickapps. But I think it is more managable for myself with 1 repo and folders for each QA  
Hope that is okey? 

Sorry, 0.1.3 was buggy. uploading 0.1.4 that has fixed the InitArray issue.
Yes, you can have everything in the same repo I guess, just point to the right fqa for each QA.

The problem you may have is that the tags you add (and that shows up as versions) will be for all QAs in your repo.
So, in effect all your QAs will have the same versions. Which may work, but if you update one QA all the other QAs will also bump their version

Edited April 6 by jgab

[Brors94 115]

12 minutes ago, jgab said:

Sorry, 0.1.3 was buggy. uploading 0.1.4 that has fixed the InitArray issue.
Yes, you can have everything in the same repo I guess, just point to the right fqa for each QA.

The problem you may have is that the tags you add (and that shows up as versions) will be for all QAs in your repo.
So, in effect all your QAs will have the same versions. Which may work, but if you update one QA all the other QAs will also bump their version

And the QA Dist Manager_Proxy cant update it self? 🤔
Didnt you have an updater for eventrunner etc earlier that could do that?  

 

[jgab 2,647]

9 minutes ago, Brors94 said:

And the QA Dist Manager_Proxy cant update it self? 🤔
Didnt you have an updater for eventrunner etc earlier that could do that?  

 

No, it can't update itself. 0.1.4 Should be named just "QA Dist Manager"

[Brors94 115]

9 minutes ago, jgab said:

No, it can't update itself. 0.1.4 Should be named just "QA Dist Manager"

Seems to be somthing strange with the uploaded file:

Please login or register to see this image.

/monthly_2026_04/image.png.c8e4afae1381ff8e7c2aec13d0783a75.png" />

When trying to open the files with the ; ending


Also crashed on Request token:
 

Please login or register to see this code.

And only version available is 0.1.2:


In the forume for Ikea Dirigera QA it is v1.0.0

 

Edited April 6 by Brors94

[jgab 2,647]

Now dirigera should work. My development version had named the QA files with a ';' at the end, which the HC3 didn't like.
0.1.4 latest.

[Brors94 115]

9 minutes ago, jgab said:

Now dirigera should work. My development version had named the QA files with a ';' at the end, which the HC3 didn't like.
0.1.4 latest.

Still got an error in the dirigera QA after deleteing the one with the files with ; on the end.

 

Please login or register to see this code.

Just to add some info:
I have an instance on one of my hc3s with the verion v1.0.0 from the forum.
Does the Dirigera support 2 at the same time?
The dist QA and the new dirigera instance is on another hc3. 
I have also changed the ip on the new uploaded fqa* 



 

[jgab 2,647]

Well, it should cope with 2 instances - it may reject a get token requests if there are a lot of requests...
I uploaded 0.1.5 that should give a better error message for failed get token and hopefully not crash.

[Brors94 115]

1 hour ago, jgab said:

Well, it should cope with 2 instances - it may reject a get token requests if there are a lot of requests...
I uploaded 0.1.5 that should give a better error message for failed get token and hopefully not crash.

Worked now
Guess it was me that was to slow. Seems like request token -->max a few sec-> click dirigerea-> max a few sec->get token

Also the update from the QA Dist Manager worked perfect  qvars didnt change only the files so that is nice
QA Dist Manager QA Dist Manager

Edited April 6 by Brors94

[jgab 2,647]

v0.1.5 - Programmatic API, allowing other QAs to request installs/updates

[Brors94 115]

8 hours ago, jgab said:

v0.1.5 - Programmatic API, allowing other QAs to request installs/updates

Could you add a uuid to the dist QA?
If i install 2 of the dist manager I could use one of them to update the other as a workaround to update the dist manager to from the UI? xD 

[jgab 2,647]

1 hour ago, Brors94 said:

Could you add a uuid to the dist QA?
If i install 2 of the dist manager I could use one of them to update the other as a workaround to update the dist manager to from the UI? xD 

If you refresh and install a new copy of dist manager, this version >= 0.1.9, should be able to update itself.
Best to have 2 copies installed, if an update would break it  

Edited April 7 by jgab

[Brors94 115]

12 minutes ago, jgab said:

If you refresh and install a new copy of dist manager, that version >= 0.1.9) should be able to update itself.
Best to have 2 copies installed, if an update would brake it  

Works perfect
I was talking with @fel-x about the possebility to see how many downloads etc from github.(like the marketplace)

This AI generated code seems to work on your yahue QA  
Maybe you/we could add a label to display each QA from all the manifest... below the rest of the QA?  

Please login or register to see this code.

 

Edited April 7 by Brors94

[jgab 2,647]

0.1.10 shows total download (all releases) in the description text, and the number of downloads per release in the dropdown with releases.

[Brors94 115]

54 minutes ago, jgab said:

0.1.10 shows total download (all releases) in the description text, and the number of downloads per release in the dropdown with releases.

Nice!  
 

Hmm, I think I am doing somthing wrong to get the downloads to show from my manifest? 🤔