Voxta docs
DevelopersModules

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=dist

Voxta.Sdk.Modules (1.13 and later) writes two files to dist/, relative to where the command ran:

FileHolds
<id>-<version>-any.zipWhat Voxta installs: the publish output without the Voxta.* assemblies Voxta provides. Your own Voxta.Modules.* stay.
voxta-module.jsonYour 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.json needs id, version and voxta, 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 one files array.
  • An any zip is offered only on the platforms module.json lists, when it lists them.
  • The commit comes from SourceRevisionId, else GITHUB_SHA.

Release from a tag

The module template has the workflows ready.

  1. Bump version in module.json, commit.
  2. 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 your author, a Download tag and a trust tag, under your category.
  • Each module offers its newest release whose voxta range 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/repo

The 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).

On this page