VoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.
Releasing VoiceStudio
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.
Credentials
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_ID,APPLE_APP_SPECIFIC_PASSWORD(not the Apple ID login password) andAPPLE_TEAM_IDfor macOS notarization and stapling.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.POSTHOG_PROJECT_TOKEN(secret) andPOSTHOG_HOST(repository variable), baked into packaged builds as the analytics token and host. They override the in-repo publishable token; 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.
Versioning
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.
Before tagging
- Merge only after required CI and review are green.
- Run the artifact-only Electron rehearsal,
.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.
- Rename
## [Unreleased]inCHANGELOG.mdto## [X.Y.Z] — YYYY-MM-DD. Lead with the largest user-visible change, keep Highlights to 3–5 bullets, 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). 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. - 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. - Confirm the version matches the intended tag.
Build a release draft
git tag vX.Y.Z
git push origin vX.Y.Z
The 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 and platform-specific
electron-stable-*.ymlfeeds - 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.
Publish
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 an Installer signing table built from those
checks (✅ signed and notarized, ⚠️ unsigned or ad hoc, with what users will
see). A macOS bundle with an invalid signature always fails, and a platform
whose signing credentials are configured fails if its installers are not signed
with them, even with allow_unsigned=true.
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 |
| 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 |
| Docker Hub | docker.yml (release published) |
Matching CUDA/ROCm tags |
| Docker Hub overview | docker.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, and :rocm timestamps move; a release never moves them |
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.
Release helper
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.
- Draft: bumps the three version files in lockstep, runs
uv lock, writes theCHANGELOG.mdsection from[Unreleased](a stable release renames it; a beta copies it), runs the version guards, commits, pushesmainand the tag. The tag push builds a draft release; nothing is public. - Publish: the same, 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' Installer signing 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.
Mobile apps
Phone apps ship on their own mobile-v* tags through the mobile-release
workflow (a draft GitHub prerelease with the APK, AAB and IPAs; store uploads use
the TestFlight and Play internal workflows). The version is the root package.json version and each run's
number is the store build number. Setup, secrets and sideloading: docs/mobile.md
→ Releasing. Publishing the draft and promoting the store builds are manual.
Beta channel
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 |
:beta, :X.Y.Z-beta.N (and -rocm) |
| 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.
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.
Package requirements
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.
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. Verify both update paths
against the final downloaded artifact, not the pre-publish build.
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.
Retry and rollback
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.