Skip to content

update-strategy.md

Latest commit

 

History

History
58 lines (38 loc) · 7.59 KB

update-strategy.md

File metadata and controls

58 lines (38 loc) · 7.59 KB
Raw

Application update strategy

Status: implemented for tagged desktop releases

Last reviewed: 2026-08-30

Research summary

Current Tauri v2 applications generally use one of three distribution patterns:

  1. The official tauri-plugin-updater with a static signed JSON feed hosted as a GitHub Release asset. Tauri documents createUpdaterArtifacts, a pinned public key, HTTPS endpoints, the latest.json platform map, download progress, and mandatory signature verification. tauri-apps/tauri-action can assemble this feed automatically when it owns the release upload.
  2. The same plugin with a dynamic update service for release channels, staged rollout, authenticated feeds, fallbacks, or downgrade policy. Atuin Desktop is a representative implementation: it chooses endpoints in Rust, retains the plugin's verified update resource, and presents progress in the renderer.
  3. Check-and-notify without in-place installation on every platform. Entracte exposes a narrow Rust check command and an opt-in startup notification, while its settings hook keeps manual checks user initiated. Atuin installs in-app on macOS but sends other platforms to downloads, demonstrating that package behavior often needs a platform-specific fallback.

GitButler adds a configurable periodic check interval and stable/nightly channels, which is useful for a continuously shipped developer tool but would introduce background traffic and channel state that CleanerX does not currently need.

Primary references:

CleanerX decision

CleanerX uses the official Rust updater plugin, the stable GitHub Releases latest.json endpoint, and a public key pinned in the application configuration. The webview receives only purpose-specific status, check, and install commands. It cannot change the endpoint, signature key, target, headers, proxy, version comparator, or installer mode.

Checks are manual. Loading Settings reads the installed version and platform support locally; it does not perform a request. Clicking Check for updates performs one HTTPS request. If the manifest reports a newer SemVer version, CleanerX retains the verified update resource in Rust, displays bounded release notes, and waits for the user to click install. Download progress is sent over a Tauri IPC channel. macOS and Linux restart CleanerX after installation; Windows hands off to the passive NSIS installer, which exits the application as required by Tauri.

The fixed stable endpoint intentionally excludes GitHub prereleases. A future beta/nightly channel would require a separate explicit product decision and endpoint policy rather than allowing the renderer to choose arbitrary feeds.

Platform and package policy

Platform In-app target Manual formats Reason
macOS arm64 .app.tar.gz DMG, application ZIP Tauri replaces the installed application bundle; the DMG remains a manual installer.
macOS x86_64 .app.tar.gz DMG, application ZIP Separate static-feed target preserves architecture matching.
Windows arm64 NSIS .exe MSI The application is native ARM64; Tauri documents that the NSIS installer shell itself runs through Windows emulation.
Windows x86_64 NSIS .exe MSI One static target cannot select both installer families; CleanerX standardizes the updater on NSIS.
Linux arm64 AppImage .deb ARM AppImages require a native ARM host, so release CI uses GitHub's Ubuntu 22.04 ARM64 runner.
Linux x86_64 AppImage .deb A static feed has one linux-x86_64 entry and cannot distinguish AppImage from .deb; non-AppImage runs do not contact the feed.

Release construction

Normal developer bundle commands remain unsigned and do not require the updater private key. Tagged releases add src-tauri/tauri.updater.conf.json, set TAURI_SIGNING_PRIVATE_KEY from GitHub Actions secrets, and ask Tauri to create update artifacts and .sig files. Linux and Windows packages are built and smoke-tested on native x64 and ARM64 GitHub runners; ARM AppImage packaging is intentionally not cross-compiled, and Windows ARM64 uses the image with Visual Studio ARM64 C++ tools. Regular product CI also builds and launch-smoke-tests the two new ARM64 targets before a tag can reach the release matrix. The release-draft job gathers every architecture, runs scripts/generate-update-manifest.mjs, and fails closed on a missing/empty signature before staging latest.json and checksums in a draft GitHub Release. A maintainer verifies the complete draft before publishing it.

Release filenames follow CleanerX-{version}-{os}-{arch}.{ext}. User-facing architecture labels are x64 and arm64, while latest.json retains Tauri's required x86_64 and aarch64 target keys.

Tauri normally skips Finder cosmetic metadata when it detects CI=true, which would silently reduce a configured DMG to Finder's default icon view. The macOS release jobs explicitly set Tauri's supported TAURI_BUNDLER_DMG_IGNORE_CI=true override, then mount each completed DMG read-only and require the tracked field-manual background, a non-empty .DS_Store selecting that background and the configured window size, the application bundle, and the exact /Applications link. A missing or stale layout fails the release before assets are staged.

WiX/MSI does not accept alphanumeric Semantic Versioning prerelease identifiers. The Windows release job therefore uses scripts/generate-windows-release-config.mjs to derive a numeric MSI-only version that sorts below the eventual stable version (0.1.0-alpha.1 becomes 0.0.65535.10001). The application, tag, updater manifest, NSIS installer, and release asset names retain the public Semantic Versioning value. Unsupported prerelease shapes fail during tag validation before platform builds begin.

Tauri's signature establishes continuity with the public key embedded in an installed CleanerX build. It does not establish operating-system publisher identity. The release warning and documentation continue to say that current binaries are unsigned and not notarized; filenames stay short and machine-predictable.