Release process

Murage releases are built by GitHub Actions workflows in the source repository, never on a developer's computer, and published to a separate public repository, FerroxLabs/murage-releases. The desktop app's updater reads that public repository, so users' machines need no token to update. This page summarizes docs/releasing.md and CONTRIBUTING.md.

Versions#

A release is a strictly newer X.Y.Z version in package.json. The release workflow refuses a version that's already published, skips a run where the version hasn't moved, and fails on a downgrade or an invalid version.

The normal flow#

1. A maintainer runs Prepare next release and picks a patch, minor or custom version.
2. That opens a small pull request that bumps the version.
3. Merging it starts the Release workflow on the exact merge commit.
4. The workflow builds every platform, verifies every file, and assembles a draft release with generated notes.
5. A maintainer reviews the draft and publishes it.

The Release workflow can also be run by hand for reruns and recovery.

What gets built#

From one pinned commit:

• macOS, Apple Silicon (arm64) and Intel (x64): DMG and ZIP, signed, notarised and stapled. Two single-architecture builds rather than one universal build, so nobody downloads both halves.
• Windows x64: an installer.
• Ubuntu 24.04 x64: a .deb and an AppImage, plus stable-named copies (Murage-amd64.deb, Murage.AppImage) for the "latest" download links, and a SHA256SUMS-ubuntu-x64.txt file covering both the versioned and stable names.

Each build also builds, verifies and pins the memory worker for its own platform before packaging. The one exception is the Intel Mac, which is packaged without it and uses keyword-only memory search.

Packages built from different commits are never combined under one version.

Checks before anything is public#

• A release is rejected if any installer, stable download name, updater feed, blockmap, size or digest is missing or inconsistent. The full list of expected files is part of the workflow; anything missing or extra fails the run rather than shipping half a release.
• Uploads go to a draft bound to one release ID. They never delete or overwrite an existing file, and an existing file is reused only when its size and SHA-256 digest match.
• Publishing waits for GitHub's own digest of every file. A wrong name, an unfinished upload or a mismatched digest stops the run, and the draft is left untouched.
• Before publishing, the README in both repositories is reviewed against the new files: install links, bundled engine information, setup requirements and known platform limits.

The Ubuntu packages

Ubuntu packages come from a manual Package Ubuntu workflow on the exact release commit. The Ubuntu 24.04 runner builds both formats, launches the unpacked app and the AppImage, runs the computer-control smoke checks, and produces the five Ubuntu files. They're attached to the matching release, the checksum file is verified, and the .deb and AppImage are tested on a clean Ubuntu 24.04 GNOME system.

Native release changes also update the checked-in license report for the bundled Cua components and prove identical hashes across the unpacked app, the .deb and the AppImage.

Verifying a download yourself

• Mac: macOS checks the signature and notarisation when you open the app.
• Windows: the installer is signed.
• Ubuntu: run sha256sum --check --ignore-missing SHA256SUMS-ubuntu-x64.txt in the download folder. See Ubuntu notes.

Release notes

Each release has generated notes on the releases page. The in-app What's new highlights the main changes once after each update.

See also: Updating Murage and Build from source.