Releases and support#

Versions#

Pimpo uses semantic versioning. From v1.0 on, the event log, routine, connector and backup formats are stable (Data formats): newer versions read older data, a version refuses data a newer one wrote rather than damage it, and every upgrade takes a snapshot first (pimpo restore brings it back).

Security fixes#

Fixes for serious issues ship within 7 days of a report, on stable and on every supported LTS line (see Reporting a vulnerability).

How a release is made#

1. make check and make e2e pass on main.
2. govulncheck ./... and npm audit --omit=dev are clean.
3. Tag vX.Y.Z, either by pushing the tag or from Actions › release › Run workflow, which asks for the version and tags the branch you pick (it refuses a version that is malformed or already exists). CI (release.yml) builds binaries for Linux, macOS, Windows and Raspberry Pi with checksums, and a draft release; then desktop.yml builds the desktop installers and attaches them:

   System	Files
   macOS, Apple Silicon and Intel	.dmg, and the .app as .tar.gz
   Windows x64	_setup.exe (NSIS) and .msi
   Linux x64 and arm64	.deb, .rpm and .AppImage

   macOS builds are signed and notarized when the repository has the APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD, APPLE_SIGNING_IDENTITY, APPLE_ID, APPLE_PASSWORD and APPLE_TEAM_ID secrets; without them they are signed ad hoc, and macOS asks to confirm the first time they open. Windows installers are signed when it has WINDOWS_CERTIFICATE (a code-signing .pfx, base64) and WINDOWS_CERTIFICATE_PASSWORD; without them SmartScreen warns on first run. The same run publishes the server image ghcr.io/turbine-dev/pimpo with the version's tag (and latest for a final release); edge follows main.

   Getting the certificates (a maintainer's task): Apple, join the Apple Developer Program, create a Developer ID Application certificate, export it as .p12 (its base64 is APPLE_CERTIFICATE), and create an app-specific password for notarization (APPLE_PASSWORD). Windows, buy an OV or EV code-signing certificate from a certificate authority and export it as .pfx. Set each secret with gh secret set NAME < file.

   The same desktop builds run on demand (Actions › desktop › Run workflow) and on pull requests that touch desktop/, keeping the installers as workflow artifacts for 14 days.

4. A maintainer checks the draft and publishes it. scripts/install.sh verifies the signature and the checksums before installing.

   GoReleaser signs checksums.txt into checksums.txt.sig (signs in .goreleaser.yaml, which runs pimpo release sign --key-env RELEASE_SIGNING_KEY), so a release fails rather than ship unsigned when the RELEASE_SIGNING_KEY secret is missing; make release-snapshot skips signing.

Updates#

Desktop app. It looks for a new version when it starts and every six hours, from the latest published release, or from the channel-beta release for people who turned on Beta versions in Settings › General. An update found shows at the top of the app and in the menu bar; installing it restarts Pimpo. Updates are signed: the app carries the project's public key (plugins.updater.pubkey in desktop/src-tauri/tauri.conf.json) and refuses anything not signed with the private one.

Before installing, the app remembers the version it leaves. Go back to the previous version then asks Pimpo to restore, on its next start, the snapshot the new version took of the data when it first started (before-VERSION), and installs the earlier version again.

Command line and servers. pimpo update checks and installs the latest release for this system, verified against the release's checksums once their signature (checksums.txt.sig) matches a release key built into Pimpo; without a valid signature it installs nothing. pimpo update --rollback puts the previous binary back (see Configuration).

For maintainers. The release workflow signs update bundles when the repository has two secrets, TAURI_SIGNING_PRIVATE_KEY (the contents of the private key file) and TAURI_SIGNING_PRIVATE_KEY_PASSWORD. It then builds the macOS .app.tar.gz, the Windows setup and the Linux AppImage with their .sig files, writes latest.json (scripts/latest-json.py) and attaches it to the draft release. Nothing points users at a draft, whose files answer 404 to everyone else: when the release is published, publish.yml copies its latest.json to channel-beta (prereleases) and updates Homebrew and winget (final releases). Without the secrets the installers are built as before and the workflow warns that automatic updates are off. The key pair was generated with npx tauri signer generate; the private key is held by the maintainers, never in the repository. Losing it means shipping a new public key in a version users install by hand.

Release key. checksums.txt is signed with an Ed25519 key: the private key (base64 of the 64-byte key) is the RELEASE_SIGNING_KEY repository secret, which only the goreleaser step of release.yml receives, and the maintainers keep a copy in ~/.config/zodim/release-signing.key, never in the repository. The public key is releaseKeys in cmd/pimpo/release.go and release_keys in scripts/install.sh. To sign by hand: pimpo release sign --key ~/.config/zodim/release-signing.key checksums.txt. To rotate, make a new key (pimpo gallery keygen --out FILE makes one in the same format), add its public key to both lists next to the old one and release that version, then switch the secret to the new key; drop the old public key a few releases later. A leaked key is rotated the same way, and the release notes say which versions to update by hand.

Gallery root key. The authors in the gallery's index.json are signed with the gallery root key (gallery.RootKeys in internal/gallery/gallery.go, a list for rotation), kept by the maintainers in ~/.config/zodim/gallery-root.key. After reviewing a new or changed author, a maintainer runs pimpo gallery sign-authors --key ~/.config/zodim/gallery-root.key DIR, both in the community gallery repository and for the starter gallery/index.json shipped in the binary. Rotating works like the release key: ship the new public key next to the old one, then sign with the new key.

Packages and the website#

Packages are published for final releases only; betas reach people through the desktop app's beta channel and the v…-beta.N Docker tags.

This page is built from the repository's documentation. Improve it on GitHub.