Packaging and release
How artifacts get built on native runners, what the site requires of them, and what has to be true before publishing.
Producing Harmony artifacts for three operating systems needs three operating systems. This page covers the build farm approach and, more importantly, exactly what the website requires of whatever comes out of it.
Why native runners
Packaging makers are guarded by host platform. A Windows machine produces Windows artifacts and nothing else — DMG creation and Apple code signing require macOS, and DEB/RPM packaging requires Linux tooling.
The practical answer is a CI matrix with one native runner per target:
| Target | Runner | Produces |
|---|---|---|
windows-x64 | Windows | Squirrel Setup.exe, portable ZIP |
mac-arm64 | macOS (Apple Silicon) | DMG + ZIP |
mac-x64 | macOS (Intel) | DMG + ZIP |
linux-*-x64 | Ubuntu | DEB, RPM, AppImage |
Each job gets a fresh machine and uploads its output as a workflow artifact.
NOTE
WSL2 is a good local Linux build and diagnosis environment, but it should not
be the sole source of official Linux packages. Keep the checkout inside the
Linux filesystem rather than a /mnt/c path, and treat the Ubuntu CI job as
authoritative.
SECURITY
Do not build release artifacts on emulated macOS. Beyond the licensing problem, an untrustworthy signing environment undermines the entire point of signing. Use real Apple hardware — hosted runner, cloud Mac, or a physical machine.
Linux build dependencies
Already declared in the packaging configuration, and needed on the runner:
sudo apt-get update
sudo apt-get install -y fakeroot dpkg rpm
- DEB requires
libgtk-3-0,libnotify4,libnss3,libxss1,libxtst6,xdg-utils; recommendslibfuse2for AppImage. - RPM requires
gtk3,libnotify,nss,libXScrnSaver,libXtst,xdg-utils.
What the site requires of an artifact
This is the part that matters, because the publisher fails closed. Every artifact record must carry:
| Field | Constraint |
|---|---|
platform | One of the seven declared platform ids |
architecture | x64 or arm64 |
filename | The real filename |
contentType | Correct for the format |
size | Exact byte size |
sha256 | Lowercase, 64 hex characters |
installKind | squirrel-windows, mac-dmg, linux-deb, linux-rpm, or linux-appimage |
updateMode | automatic or manual |
signature | Status, publisher, timestamped, notarized |
IMPORTANT
installKind values are exactly those strings — not bare dmg, deb, rpm,
or appimage. The schema rejects anything else, which is the intended
behaviour: a typo should fail publication rather than produce a manifest the
installers cannot act on.
Notarization is a macOS concept. Windows and Linux artifacts must leave
notarized null rather than claiming it.
Publication is atomic and fails closed
The publisher uploads immutable artifacts, verifies them, writes the immutable version manifest, verifies that, and replaces the channel document last.
Consequences worth internalising:
- A half-published release is never live, because the channel pointer moves last.
- Size and SHA-256 are verified before the artifact is served, and again by the installer before execution.
- A platform without a verified artifact is omitted from the manifest, and the site renders only what the manifest contains. It is never shown as a broken or speculative download.
Unsigned builds
An unsigned build can reach the preview channel only, and only behind an explicit publisher flag. Stable publication requires:
- Windows — Authenticode validation and a trusted timestamp
- macOS — Developer ID signing, hardened runtime, notarization, stapling
- Linux — signed checksums
Keep signing on tag-triggered release jobs, never on ordinary pull requests, and store certificates and notarization credentials as encrypted secrets behind a protected release environment.
Before publishing a platform for the first time
CI proves the package builds. It does not prove the package works.
- Install on a clean machine of that platform.
- Launch, connect a provider, run one real turn.
- Verify PTY behaviour, sleep and resume, and update behaviour.
- Uninstall cleanly.
- Confirm the package embeds the final commit SHA and includes the Pi runtime.
- Verify the artifact's signature and hash independently.
WARNING
An empty vendor/ directory silently ships a build without the Pi runtime.
Build with NALA_REQUIRE_PI_RUNTIME=1 so this fails loudly. npm run test:packaged-self-test is the only suite that catches packaging-level gaps.
For macOS specifically, verify Gatekeeper acceptance, DMG mounting, drag-to- Applications, and first launch on both Apple Silicon and Intel if you claim both.
When a platform becomes available
Publishing an artifact is not the whole change. The documentation states platform availability in several places, and all of them move together:
/docs/reference/platform-support/docs/reference/feature-status/docs/reference/known-limitations/docs/getting-started/macosor/docs/getting-started/linux- The platform row on the docs home
Do not flip any of them until the artifact is published and verified.