# Packaging and release Source: https://docs.ideharmony.com/developers/packaging 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: ```bash sudo apt-get update sudo apt-get install -y fakeroot dpkg rpm ``` - **DEB** requires `libgtk-3-0`, `libnotify4`, `libnss3`, `libxss1`, `libxtst6`, `xdg-utils`; recommends `libfuse2` for 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. 1. Install on a clean machine of that platform. 2. Launch, connect a provider, run one real turn. 3. Verify PTY behaviour, sleep and resume, and update behaviour. 4. Uninstall cleanly. 5. Confirm the package embeds the final commit SHA and includes the Pi runtime. 6. 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/macos` or `/docs/getting-started/linux` - The platform row on the docs home Do not flip any of them until the artifact is published and verified. ## Related - [Cross-platform builds](/docs/developers/cross-platform) - [Platform support](/docs/reference/platform-support) - [Testing](/docs/developers/testing)