kandev/docs/desktop-tauri-signing.md

Tauri Desktop Signing

The release workflow signs desktop artifacts opportunistically. Complete macOS and Windows signing inputs produce signed/notarized artifacts. Missing or incomplete inputs do not block the release; those platform artifacts are built unsigned and the GitHub release notes get an unsigned-artifact warning.

Unsigned desktop artifacts may require manual OS security bypasses and must not be presented as trusted downloads.

Use desktop_validation_only=true for maintainer inspection builds. That mode uploads workflow artifacts but does not publish a GitHub release, npm packages, Homebrew updates, or public container tags.

Release backfills build application code and artifacts from the requested immutable tag. Updater signing-readiness validation is control-plane logic and runs from github.workflow_sha, so a workflow fix on main can recover an existing tag without moving it or substituting main-branch application source.

macOS

Signing inputs:

• APPLE_CERTIFICATE: base64 .p12 Developer ID Application certificate.
• APPLE_CERTIFICATE_PASSWORD: export password for the .p12.
• KEYCHAIN_PASSWORD: temporary CI keychain password.

Notarization inputs, choose one path:

• Apple ID path: APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID.
• App Store Connect API path: APPLE_API_KEY, APPLE_API_ISSUER, APPLE_API_KEY_P8.

Optional:

• APPLE_PROVIDER_SHORT_NAME when the Apple ID belongs to multiple provider teams.

Windows

Signing inputs:

• WINDOWS_CERTIFICATE: base64 .pfx code signing certificate.
• WINDOWS_CERTIFICATE_PASSWORD: export password for the .pfx.

Optional:

• WINDOWS_TIMESTAMP_URL: timestamp server, defaults to http://timestamp.digicert.com.
• WINDOWS_SIGNTOOL_PATH: custom signtool.exe path.

Linux desktop artifacts are checksum-gated. The x64 .deb/.rpm artifacts are built on Ubuntu 22.04 for an older glibc baseline. The arm64 artifacts use GitHub's Ubuntu 24.04 arm64 runner baseline. GPG/RPM signing can be added later without changing the macOS and Windows publisher-identity layers.

Updater artifacts

Tauri updater signing is distinct from macOS and Windows code-signing credentials. Configure these GitHub Actions secrets:

• TAURI_SIGNING_PRIVATE_KEY: contents of the private key generated by pnpm tauri signer generate. Keep this value only in the CI secret store.
• TAURI_SIGNING_PRIVATE_KEY_PASSWORD: password for the updater private key. It may be empty only when the generated key has no password.

The corresponding public key is embedded in the desktop updater configuration; the private key is never committed or written into release metadata. A release with the updater key produces signed macOS .app.tar.gz, Linux .AppImage.tar.gz, and Windows NSIS .zip bundles. The release collector verifies all five target/signature pairs before generating latest.json.

Tauri updater signing proves payload integrity and is required for every target. macOS signing/notarization and Windows code signing separately prove publisher identity to the operating system. Missing OS credentials do not block Tauri-signed updater artifacts; those macOS and Windows builds retain the unsigned-development warning in release notes until identity signing is configured. See ADR-0040.

The collector verifies each payload cryptographically with the same public key embedded in tauri.conf.json. A CI private key that does not match the shipped public key fails before publication.

Installers remain available when the updater signing input is absent, but latest.json is not published. A partially Tauri-signed platform set fails release verification instead of publishing an incomplete update feed.