Electron is the only maintained desktop distribution. Tauri ended at v0.5.3; its signed updater feeds and installers are immutable compatibility assets.
Shared store inputs and platform handoffs are defined in
STORE-PUBLISHING.md. Microsoft Store, Snap Store and
Mac App Store are not maintained release channels until each has completed its
first verified production publication.
Snap Store packaging runs through .github/workflows/snap-store.yml. Each
v* tag builds the strict Snap and uploads it to the Store's candidate
channel using SNAPCRAFT_STORE_CREDENTIALS from the snap-store environment.
Stable is never automatic: after the runbook checks, the repository owner
dispatches the workflow with promote_revision. Follow the
Snap Store runbook for confinement checks,
candidate verification, evidence and rollback. Do not add a Snap to the
maintained-channel table below until its stable listing is independently
install-verified.
Microsoft Store EXE preparation uses the owner-dispatched
microsoft-store.yml workflow and the
Microsoft Store runbook. It builds a distinct
Store installer without changing direct-download artifacts. Staging its
immutable versioned URL requires owner approval; Partner Center submission and
publication remain manual owner actions.
Mac App Store preparation uses the manual, private mac-app-store.yml workflow
and the Mac App Store runbook. The workflow cannot
build while the bundled-runtime compliance gate is unresolved and never uploads
to App Store Connect. MAS packages use App Store updates; direct macOS packages
keep the existing application updater and Developer ID notarization path.
Electron publication uses these GitHub Actions secrets:
ELECTRON_MACOS_CSC_LINKandELECTRON_MACOS_CSC_KEY_PASSWORDfor the Developer ID Application.p12certificate and its password.ELECTRON_MAC_APP_STORE_CSC_LINK,ELECTRON_MAC_APP_STORE_CSC_KEY_PASSWORD,ELECTRON_MAC_APP_STORE_INSTALLER_LINK,ELECTRON_MAC_APP_STORE_INSTALLER_KEY_PASSWORDandELECTRON_MAC_APP_STORE_PROVISIONING_PROFILEfor private MAS packaging. These are separate from Developer ID credentials and do not authorize upload or publication.APPLE_API_KEY(raw.p8PEM text),APPLE_API_KEY_IDandAPPLE_API_ISSUERfor macOS notarization and stapling. Use an App Store Connect team key with Developer access. The packaging step writes the key into a private temporary file and removes it on success or failure. Apple ID passwords are not used by this workflow.ELECTRON_WINDOWS_CSC_LINKandELECTRON_WINDOWS_CSC_KEY_PASSWORDfor Windows Authenticode signing. The macOS certificate cannot sign Windows apps.APP_STORE_CONNECT_KEY_ID,APP_STORE_CONNECT_ISSUER_IDandAPP_STORE_CONNECT_API_KEYin theapp-store-connectenvironment for the iOS TestFlight upload (mobile.md). TestFlight is not a release channel.ANDROID_UPLOAD_KEYSTORE,ANDROID_UPLOAD_KEYSTORE_PASSWORD,ANDROID_UPLOAD_KEY_ALIAS,ANDROID_UPLOAD_KEY_PASSWORDandGOOGLE_PLAY_SERVICE_ACCOUNT_JSONin thegoogle-playenvironment for the Play internal testing upload (mobile.md). Play internal testing is not a release channel either.- The repository
GITHUB_TOKENfor draft creation and asset uploads. DOCKERHUB_USERNAMEandDOCKERHUB_TOKENfor the Docker Hub mirror.- No analytics secret is needed: the destination is the public Supermetry site
id in
config/analytics.json. Analytics still sends nothing without a yes at the first-run consent prompt.
The archived TAURI_SIGNING_PRIVATE_KEY* secrets are retained only so the final
Tauri release can be audited. The Tauri release workflow has been removed; every
new version ships through electron-release.yml. TAURI_SUNSET_TAG must continue to identify v0.5.3 so Electron releases
can copy the final signed latest.json and latest-user.json feeds unchanged.
Those feeds must always point to immutable v0.5.3 Tauri assets; old Tauri clients
must never receive an Electron installer.
The root package.json is the single source of truth for the maintained app
version. Electron Builder reads it directly. Keep these active mirrors equal:
pyproject.tomlbackend/core/version.py(_FALLBACK_VERSION)
The archived Tauri manifests stay frozen at their final release. Do not bump or
rebuild them. tests/test_app_version.py enforces the active version contract.
Version bumps are manual and require owner approval. Until a bump is requested,
main may remain at the latest released version. For a release, bump the
canonical version and both maintained mirrors together, then tag that exact
version only after validation.
- Merge only after required CI and review are green.
- Run the artifact-only Electron build,
.github/workflows/electron-build.yml, and inspect all five outputs: Linux x64, Windows x64, Windows ARM64, macOS arm64, macOS x64. Windows ARM64 is experimental: a failed leg does not block the other four. It first checks the setup screen, then installs and starts the managed Python runtime in a separate temporary profile on Linux, Windows and Apple Silicon. Intel Macs retain packaging/setup checks under their existing UI/remote-only contract. The local-runtime test downloads runtime packages, keeps model downloads disabled, verifies the live backend connection and clean shutdown, and removes the test profile. A setup-screen check alone is not evidence that runtime installation works. - Verify a packaged launch and managed backend startup on the changed platforms.
- Fold the
changelog.d/fragments into## [Unreleased](scripts/release.pydoes this and deletes them; by hand:uv run python scripts/changelog_fragments.py), then rename## [Unreleased]inCHANGELOG.mdto## [X.Y.Z] — YYYY-MM-DD. Open the section with its Highlights (3–5 bullets, the largest user-visible change first; the workflow puts the Download table above them), include migration steps and real screenshots when relevant, and verify human contributors and bug reporters from the tag comparison and included PRs. The release workflow adds a### Contributorsblock to the GitHub Release notes by itself: everyone who committed since the latest stable release, plus the authors of PRs merged in that span (ranked by commits; bots, AI agents and unlinked placeholders are never listed). A second or later beta first lists who is new since the previous beta, then that full list. It does not find bug reporters, and it skips the block when the changelog section already has a### Contributorsheading, so write one by hand when you want roles or reporters credited. Indocs/install/issue-tracker.md, changeFixed on mainrows toFixed in releaseand update the release named at the top. - Run
uv run pytest tests/test_app_version.py tests/test_changelog_style.py -q. - Audit contributor agreements:
git fetch origin cla-signatures, thenGH_TOKEN=... python scripts/cla_audit.py. Follow up with each unsigned contributor it lists, asking them to sign.github/CLA-1.0.md(or their employer the Corporate CLA). This step applies once the CLA workflow andscripts/cla_audit.pyare onmain. The audit aborts if Git cannot read any file’s history; restore access to missing objects and rerun before treating its contributor list as complete. The unsigned count includes only contributors required to sign by the existing checker. Exempt account IDs attributed through tool/placeholder commits keep a separate provenance-review row; no signature is invented for them. JSON reportssignature_present,signing_requiredandprovenance_review_required; legacysignedmeans actual signature-store presence only. Review other unsigned and unresolved identities independently. A successful audit exit means the inventory completed, not that every signature or provenance question is resolved. - Confirm the version matches the intended tag.
- Rehearse the release from the commit you will tag.
Run the real release workflow without a tag before every tag, and whenever a release workflow change needs proof:
gh workflow run electron-release.yml --ref <branch> -f rehearsal=trueIt builds the dispatched commit exactly as a tag would: every desktop package
(Linux x64, Windows x64 and ARM64, macOS arm64 and x64), the CLI bundle inside
them, the omnivoice-tts runtimes, the Android APK/AAB and the unsigned iPhone
IPA, and the packaged smoke tests. The release job then collects every asset and
runs prepare_electron_release.py --rehearsal against the version in
package.json (it must be X.Y.Z or X.Y.Z-beta.N, and CHANGELOG.md must have
its section), the updater feed checksum and channel checks, the Tauri sunset
feeds for Stable, and the signing table. The notes, SHA256SUMS.txt and the
installers stay on the workflow run for 3 days. When some build legs fail, the
rehearsal still verifies the ones that built, then fails and lists the missing
legs in the run summary; a release still stops at the first failed leg.
It never publishes: no tag, no GitHub Release or draft, no feed upload, no
Docker or Android repository dispatch. publish, release_tag and
allow_unsigned are refused with rehearsal. macOS builds are signed and
notarized when the Apple secrets exist, like a release. Phone builds skip the
protected mobile-release environment, so the APK/AAB are unsigned. SignPath is
skipped unless you add -f signpath_policy=test-signing, which signs the Windows
installers with the project's test certificate; the release policy is never used.
It does not prove the publishing steps themselves, the Android repository update,
release-signed Android or App Store builds, SignPath release approval, or Docker
images (docker.yml builds those on main).
Android download notes use the mobile job's APK signature-verification report,
bound to the collected APK's SHA256. Rehearsals show an explicit warning rather
than release-signing proof. A failed rehearsal verification is unverified,
not proof of an absent signature: corrupt packages and verifier failures can
also fail the check. A missing, unsigned, unverified or mismatched APK report
stops tagged release notes. AAB links identify the Play upload bundle, whose signature
is not verified by the APK check. Existing release-keystore requirements remain
mandatory. Verification runs inline in the workflow, so recovery builds from
main can still check out older tags without needing a new helper in that tag.
git tag vX.Y.Z
git push origin vX.Y.ZThe tag starts .github/workflows/electron-release.yml. It builds the same five
targets (a failed experimental Windows ARM64 leg does not block the others, and
its feed is checked only when it was published), validates packaged startup and updater metadata, creates or
updates a draft, and uploads:
- Electron installers named
VoiceStudio-<version>-<os>-<arch>.<ext>(releases up to v0.5.7-beta.3 usedVoiceStudio-Electron-*) and platform-specificelectron-stable-*.ymlfeeds; feed file names never change, and each feed names its own installer, so older clients update across the rename - per-platform
store-artifact-manifest-*.jsonprovenance records SHA256SUMS.txt- authored CHANGELOG release notes
- immutable copies of the final Tauri updater feeds for old clients
Tag pushes never publish the Electron GitHub Release, and they do not build
Docker images (the Snap workflow above uploads tags to candidate only). Inspect the
draft and downloaded installers first.
If the workflow itself needs a fix after tagging, keep the tag immutable. Merge
and validate the workflow fix on main, then dispatch electron-release.yml
from main with release_tag=vX.Y.Z. Every build still checks out the exact tag;
only the workflow definition comes from main.
Dispatch electron-release.yml for the exact tag with publish=true. Signing
and notarization are required by default. The owner may explicitly set
allow_unsigned=true. Never select that exception without the owner's decision.
Every build, published or not, verifies what each platform leg actually ships
and the release notes open with one Download table: every desktop and phone
download with its signing, built from those checks (✅ signed and notarized, allow_unsigned=true.
In particular, configured macOS releases still run the Gatekeeper assessment
when the unsigned exception is needed for Windows; that exception does not
skip macOS signature or notarization verification.
The owner can delegate it: accounts listed in the UNSIGNED_RELEASE_PUBLISHERS
Actions variable (comma-separated logins, Settings → Secrets and variables →
Actions → Variables; only admins can edit it) may also dispatch or re-run an
unsigned publish. Remove a login to revoke it; an empty variable means owner only.
Publishing the GitHub Release triggers the Docker workflow for that tag. Docker
release tags are never built from a tag push, and :latest only ever tracks
main; a release does not move it.
After publication, verify each maintained channel:
| Channel | Workflow | Verification |
|---|---|---|
| GitHub Release | electron-release.yml |
Linux x64, Windows x64 (+ ARM64 when its leg passed), macOS arm64 and x64 installers, updater feeds, checksums, CHANGELOG notes, retained v0.5.3 Tauri feeds |
| Phone downloads | electron-release.yml → mobile-release.yml |
Signed Android APK/AAB and unsigned iOS sideload IPA from the same tag |
| GHCR CUDA | docker.yml (release published) |
:X.Y.Z, :X.Y, :stable manifests |
| GHCR ROCm | docker.yml (release published) |
:X.Y.Z-rocm, :X.Y-rocm, :stable-rocm manifests |
| GHCR CUDA arm64 | docker.yml (release published) |
:X.Y.Z-cuda-arm64, :X.Y-cuda-arm64, :stable-cuda-arm64 manifests (linux/arm64) |
| Docker Hub | docker.yml (release published) |
Matching CUDA/ROCm/CUDA arm64 tags |
| Docker Hub overview | dockerhub-description.yml |
Read the Update Docker Hub description step log; the step may continue after a 403 |
| Rolling containers | docker.yml on main pushes only |
:latest, :main, :rocm and :cuda-arm64 timestamps move; a release never moves them |
For the Homebrew installation method, update
Casks/voicestudio.rb in the official tap
after publishing a stable release: set its version and both architecture-specific
DMG SHA-256 values from that release’s SHA256SUMS.txt. Validate with
brew style --cask debpalash/tap/voicestudio,
brew audit --cask --online debpalash/tap/voicestudio and
brew fetch --cask --all-platforms debpalash/tap/voicestudio before merging the tap
update. Keep prereleases out of this stable cask.
A missing channel is a release bug. There are no RC tags; the one prerelease is
the opt-in Beta channel (below). Previews between betas are builds from
main (the electron-build.yml artifacts or Docker :latest), never a side
branch. No Tauri build is maintained.
make release (or uv run python scripts/release.py) cuts a release from any
branch. It shows the last release and the version on main, then asks stable
or beta and suggests the new tag (v0.5.7, or v0.5.7-beta.1, -beta.2, ...
for a beta; the beta suffix is always -beta.N). If package.json already names
the upcoming release it uses that version; if that version is already tagged it
moves to the next patch. Choices are arrow-key menus (up/down or j/k,
Enter; Esc cancels) that fall back to typed answers when there is no terminal.
It then asks draft or publish, prints the plan
(including switching to main and fast-forwarding it), and only proceeds when you
type the tag name.
- Two runs, because
mainonly changes through pull requests. The first run bumps the three version files in lockstep, runsuv lock, writes theCHANGELOG.mdsection from[Unreleased](a stable release renames it; a beta copies it, pointing its download links at the beta's own release files), runs the version guards, commits onrelease/vX.Y.Z[-beta.N]and opens its pull request. Once that merges, run the helper again with the same version:mainalready has it, so it changes nothing and only tags. - Draft: the tag push builds a draft release; nothing is public.
- Publish: the tag push, then dispatches
electron-release.ymlwithpublish=true. It lists which platforms have signing secrets (macOS needs the Developer ID and notarization set, Windows needsELECTRON_WINDOWS_CSC_LINKand its password) and, for any platform without them, stops unless you explicitly accept shipping that platform unsigned. The dispatch'sallow_unsignedflag only accepts platforms without credentials: a platform with signing configured must still produce signed installers, and the notes' Download table shows each platform's measured result. --publish vX.Y.Z[-beta.N](make release-publish TAG=…) publishes an existing draft build later.--dry-run(make release-dry) prints the plan and changes nothing.
It does not replace the post-release verification below; run it every time.
Phone apps build from the same vX.Y.Z or vX.Y.Z-beta.N tag as desktop.
electron-release.yml calls mobile-release.yml and waits for the signed
Android APK/AAB and unsigned iOS sideload IPA before creating or publishing the
GitHub Release. All downloads share its version and SHA256SUMS.txt. A failed
phone build blocks publication; do not publish a desktop-only release manually.
Docker CUDA, ROCm and CUDA arm64 builds are dispatched for that same tag after
publication; verify their completion before calling the release complete.
App Store signing and store promotion remain separate from GitHub downloads.
The unsigned IPA requires signing with the user's own Apple ID to sideload; it
is not a TestFlight build. Apple certificate availability cannot suppress this
artifact. Manual mobile-release runs can set release_ref to an existing tag
and signed_ios=false to recover phone artifacts without changing the tag.
Legacy mobile-v* tags remain supported only for historical standalone builds.
Beta is a second release channel cut from main, for testers who opt in under
Settings → Updates → Update channel (user guide). It
has no soak period, no side branch and no cherry-picks.
| Stable | Beta | |
|---|---|---|
Tag and package.json version |
vX.Y.Z |
vX.Y.Z-beta.N |
| GitHub Release | full release, becomes latest |
prerelease, never latest |
| Update feed | electron-stable-<os>-<arch> |
electron-beta-<os>-<arch> |
| Docker | :X.Y.Z, :X.Y, :stable (and -rocm, -cuda-arm64) |
:beta, :X.Y.Z-beta.N (and -rocm, -cuda-arm64) |
| Snap / Microsoft Store / Mac App Store | yes | no (Stable-only) |
| Tauri sunset feeds | copied into the release | not copied |
Cutting a beta: with owner approval of the version, bump package.json,
pyproject.toml and _FALLBACK_VERSION to X.Y.Z-beta.N together, run uv lock
(it records the PEP 440 form X.Y.ZbN; the lockstep test compares versions, not
strings), add a
## [X.Y.Z-beta.N] section to CHANGELOG.md, tag from main, then run
electron-release.yml with publish. The workflow derives the channel from
the version (prepare_electron_release.py --print-channel), stamps it into every
platform feed, publishes with --prerelease --latest=false, and dispatches
Docker with promote_stable=false. Any other prerelease shape (-rc, -alpha)
is rejected. The release is refused if it carries another channel's update
feed (a stable electron-stable-* or latest* feed on a beta, a beta feed on
stable), and after publishing the workflow checks that releases/latest still
points at the newest stable.
Promoting to Stable is a normal vX.Y.Z release from main. Beta users roll
onto it automatically because the updater compares semver (X.Y.Z-beta.N sorts
below X.Y.Z). The verification table above applies to Stable; for a beta also
confirm the GitHub Release is flagged Pre-release, releases/latest still
points at the last stable, and :stable and :X.Y did not move.
Linux packages must carry the native helper's non-glibc libraries under
resources/native/lib. Packaging checks reject missing or host-resolved
libraries. AppImages use the static runtime, which needs no host libfuse2; test
the downloaded image on a clean host because build-runner libraries can hide
relocation errors.
Every direct desktop installer except Intel macOS ships the OmniVoice GGUF
runtime under resources/bin/ (#2780). electron-release.yml and the
packaging rehearsal call build-omnivoice-tts.yml (desktop: true) and stage
each platform's artifact into electron/build/omnivoice-tts/; Windows ARM64
ships the x64 build. Each platform ships tts-server-<platform> (the opt-in resident server,
#3654) next to omnivoice-tts-<platform>; the build, the staging step and
packaging-contract.mjs all fail if it is missing or absent from the manifest.
Signing rewrites the binaries, so the build refreshes
bin/checksums.sha256 after signing (electron/omnivoice-tts-bundle.mjs; on
macOS before the bundle is sealed). packaging-contract.mjs fails a release
whose installer lacks the runtime, whose manifest no longer matches the shipped
bytes, or (macOS) whose runtime is unsigned. A failed runtime build fails the
release; there is no fallback that ships without it.
Linux release AppImages include gh-releases-zsync update information and a
versioned .AppImage.zsync asset for AppImageUpdate/AppImageLauncher. Release
images follow the latest stable GitHub release. The build uses readelf and
zsyncmake (Ubuntu package zsync) to embed this information before
regenerating electron-updater's blockmap and checksums; the existing in-app
updater still uses its separate channel manifest. Images up to v0.5.7-beta.3 look
for VoiceStudio-Electron-*-linux-x64.AppImage.zsync, so AppImageUpdate cannot
move them to a renamed release; they update through the in-app updater. Verify both update paths
against the final downloaded artifact, not the pre-publish build.
Windows ROCm RDNA 2 GPU speech uses the in-repo HIP CTranslate2 pinned in
rocm10.ctranslate2 of scripts/windows-rocm-recipe.json (release
ct2-rocm-4.8.4-78b1e17). It is a dependency asset, not part of a release:
releases reuse it unchanged. To rebuild (new upstream source or targets), edit the workflow's source pins
(CT2_BASE, CT2_TARGETS, CT2_TREE, CT2_VERSION) and the recipe's target
list, and set a new RELEASE_TAG in .github/workflows/ct2-rocm-windows.yml
(the publish job fails if the tag already exists, since the recipe pins its
bytes and gh release create would otherwise reuse the old tag). Add the new
archive URL to _SOURCES in backend/core/windows_rocm/ct2_recipe.py, run the
CTranslate2 ROCm (Windows) workflow, verify the downloaded archive's size and
SHA-256 independently, then copy the run's printed pins (pins.json) into the
recipe and update the exact-pin test in tests/test_windows_rocm_rocm10.py.
Electron update manifests use platform and architecture channels. Confirm every manifest names an uploaded installer, reports the tagged version, and matches the artifact bytes. Exercise at least one installed update hop before publication.
Signed Electron macOS releases require a paid Apple Developer identity and the
secrets above. A draft build without credentials can remain unsigned; a normal
publish refuses missing signing/notarization credentials and verifies both the
signature and stapled ticket. Do not accept allow_unsigned merely to close a
signing report. Tauri signing keys cannot sign Electron packages. Existing
artifact names, app IDs, data paths, and updater channels are compatibility
contracts.
Windows installers can instead be signed through SignPath Foundation: set the
SIGNPATH_API_TOKEN secret and the SIGNPATH_ORGANIZATION_ID,
SIGNPATH_PROJECT_SLUG and SIGNPATH_SIGNING_POLICY_SLUG variables, and leave
ELECTRON_WINDOWS_CSC_LINK unset. The Windows build leg then signs the installer,
and electron/scripts/apply-signed-windows.mjs regenerates the blockmap and the
feed's sha512/size before upload. Policy and owner checklist:
code-signing-policy.md.
Re-run failed jobs in the same workflow run when possible. The release job replaces only the current draft's Electron assets. It refuses to overwrite a published release.
Clients only accept newer versions. To roll back, fix or revert the code, choose a higher patch version with owner approval, test it, and publish that version. Do not move or recreate an existing tag.
GitHub's merge queue is available only to repositories owned by an organization. This repository is owned by a user account, so the queue cannot be turned on. The current setup instead:
- The
mainruleset requires branches to be up to date before merging. Merge currentmaininto a stale PR and wait for its checks again; green checks against an older base do not prove the combined result. - Auto-merge is on:
gh pr merge N --auto --mergemerges a PR once its required checks pass. - The required aggregate CI status is Tests (backend + frontend), which waits for every job in
ci.yml(Python tests, platform smokes, Electron tests, renderer smokes, UI crawler, Desktop UI, Linux native package, installer contracts and the release smoke). A failure in any of them blocks the merge without listing each job in the ruleset. CLA gate, Commit identities, CLA and Commit identity policy are also required. - A PR's CI tests it merged with
mainasmainstood when the run started. The up-to-date requirement prevents accepting that result after the base changes. After every merge, wait for that exactmaincommit's post-merge workflows; when a run fails, fixingmaincomes before the next merge.
Moving the repository to an organization would make the queue available, and the workflow support for it stays in place. The workflows are ready: ci.yml runs on merge_group, and merge-queue-checks.yml reports the PR-level required checks ("CLA gate", "Commit identities", "CLA", "Commit identity policy") on the queue's commit, because they cannot run there. tests/test_merge_queue.py keeps those names equal to the ruleset's required list; change both together.
On the queue commit, ci.yml compares the commit with its base to decide the documentation-only and Electron scopes, as it does for a pull request. The pass cache (see .github/CONTRIBUTING.md → Quality gates) lets a queued job skip when its inputs match a green run on main, so jobs whose inputs the queued pull requests did not touch do not run again. Pushes to main always run in full.
To turn it on once the repository belongs to an organization (Settings → Rules → Rulesets → main):
- Add Require merge queue: method Merge commit, build concurrency 1–3, minimum group size 1, wait time 0–5 minutes, status check timeout 60 minutes.
- Under Require status checks to pass, keep Require branches to be up to date before merging unticked; the queue makes it unnecessary.
- Merge PRs with Merge when ready (the queue button) instead of Merge.
gh pr merge N --mergejoins the queue once it is on.
Try it on one PR first. If a queued PR stalls, a required check name in the ruleset no longer matches a job or status the queue commit reports: compare the ruleset with tests/test_merge_queue.py.
The Docker workflow publishes canonical voicestudio, compatibility
omnivoice-studio, and voicestudio-buildcache packages under the lowercase
repository owner on GHCR. Forks publish only into their own GHCR namespace;
upstream remains under ghcr.io/debpalash. CUDA, ROCm and CUDA arm64 share this
namespace rule, including registry layer caches and manual release backfills.
Docker Hub publishing still requires its existing explicit credentials and
retains its configured image coordinate. Publishing a preview from a fork does
not publish an upstream application release.