Publishing a module
Pack a Voxta module for a GitHub release with Voxta.Sdk.Modules, release it from a tag, and let users install and update it from your repository.
A GitHub repository is a module source. Users add it under Settings → AI Setup → Module Sources, and its releases are the listing: no index file is committed, and nothing in between hosts it.
Voxta's own modules, and repositories Voxta Cloud trusts to publish, go to the official Voxta Cloud source with modulepublish (the Voxta.ModulePublish dotnet tool, run by voxta-module-actions from the job that built the release). Anyone else publishes through GitHub releases, as below.
Pack
dotnet publish -c Release -p:VoxtaModulePack=distVoxta.Sdk.Modules (1.13 and later) writes two files to dist/, relative to where the command ran:
| File | Holds |
|---|---|
<id>-<version>-any.zip | What Voxta installs: the publish output without the Voxta.* assemblies Voxta provides. Your own Voxta.Modules.* stay. |
voxta-module.json | Your module.json as built, the Voxta.Sdk.Modules version it was built against, the .NET SDK, the commit, and each zip's sha256. |
{
"module": { "id": "Voxta.Modules.Weather", "version": "0.2.0", "voxta": ">=1.13.0" },
"builtAgainst": "1.13.0",
"dotnetSdk": "10.0.300",
"commit": "…",
"files": [
{ "rid": "any", "name": "Voxta.Modules.Weather-0.2.0-any.zip", "sha256": "…" }
]
}module.jsonneedsid,versionandvoxta, or the release is skipped.dotnet publish -r <rid>packs<id>-<version>-<rid>.zip, for that platform only. A release for several platforms lists every zip in onefilesarray.- An
anyzip is offered only on theplatformsmodule.json lists, when it lists them. - The commit comes from
SourceRevisionId, elseGITHUB_SHA.
Release from a tag
The module template has the workflows ready.
- Bump
versioninmodule.json, commit. git tag v0.2.0 && git push --tags. In a repository with several modules, tag<module id>/v0.2.0.
release.yml checks the tag matches module.json, packs, attests the zip, and creates the GitHub release with both files. A version with a suffix (v0.2.0-beta.1) is a GitHub pre-release, which Voxta lists only when the source shows pre-releases. Drafts, and releases without a voxta-module.json, are skipped.
Without the template: create a release and upload the zip and voxta-module.json as assets.
What users see
- They add
owner/repo(or any github.com URL in it) on Module Sources. For a private repository, they connect GitHub in Connected Accounts first. Its modules show in Add Modules with the others, with yourauthor, a Download tag and a trust tag, under yourcategory. - Each module offers its newest release whose
voxtarange includes their Voxta, with a build for their machine. - Unless Voxta has verified the release, installing or updating shows a warning every time: the code is third-party, and any repository can claim an id that is not built in. Updates from GitHub sources are left out of Upgrade All. Users update from your source's page.
- Voxta Full only: GitHub sources come from the GitHub module, which Lite does not have.
Voxta offers a file only when GitHub's own hash of the asset matches the sha256 in voxta-module.json, and checks the download against it. A zip replaced after its release was made is not offered.
Fixing a release
When a later Voxta breaks a release, cap its range without rebuilding: Actions → edit release in the template, with a range such as >=1.13.0, <1.15.0. The same workflow yanks a release, or un-yanks it. It re-uploads voxta-module.json, and servers see the change on their next refresh. Deleting the release works too.
Verification by Voxta
Only the official Voxta Cloud vouches for a module. Voxta reviews the code of the third-party repositories it knows, by commit, and users see the result as a tag: Verified, Not verified yet, Not verified, Flagged or Blocked (see Verification).
A review is of the commit's source, not of the zip you uploaded. So a release is Verified only when its zip carries GitHub's build attestation, showing a GitHub-hosted runner built it from that commit, with your repository's own workflow or voxta-module-actions'. The template's release.yml does this. A release without a commit in its voxta-module.json, or a zip uploaded by hand, is never verified.
Checking a release yourself
Every zip the template's workflow builds is attested by GitHub:
gh attestation verify Voxta.Modules.Weather-0.2.0-any.zip --repo owner/repoThe build is pinned (packages.lock.json, deterministic compiler output). Rebuilding the tag with dotnet publish -c Release -p:ContinuousIntegrationBuild=true on the .NET SDK voxta-module.json names gives the same DLL. The zip itself differs (file times).
Installing and live reload
Load a module you are writing as a dev folder and reload it without restarting Voxta, install a built module from a .zip or .dll, and find out why one does not load.
SDK
The Voxta SDK on NuGet: what each of the four packages does, which ones your module references, and how SemVer versioning affects compatibility.