Release pipeline

This page explains why many Pear desktop release flows use three operations: stage, provision, and multisig, and how release lines and the deployment directory fit around them.

Read it before you run commands so the mental model matches the CLI (concrete steps live under Deploy your application and Build desktop distributables).

The short version

Centralized deploy pipelines often separate staging servers, preview, and production. Pear can fold similar trust boundaries into different Hyperdrives addressed by different pear:// links:

1. You stage a folder of builds into a drive used for iteration,
2. You provision from a versioned stage into a leaner prerelease drive, and
3. You multisig-commit into production so a quorum of signers must agree. Each hop can shrink history or raise assurance.

OTA update event lifecycle

A running Pear desktop app polls the Hyperdrive behind its upgrade link, downloads new application data when the Hypercore length advances, and emits two events from pear.updater. The host process forwards them to renderers so the UI can react:

• updating fires when the updater begins streaming new blocks; treat it as "background work in progress".
• updated fires when the new build is fully on disk; it is safe to swap.
• bridge.applyUpdate() (renderer side) calls pear.updater.applyUpdate() (updater worker side). applyUpdate() renames the application directory to the new build and deletes the old one — until the process restarts, the running code is still the old build.
• bridge.appAfterUpdate() triggers app.relaunch() and app.exit(0). On Linux AppImage you usually relaunch with process.env.APPIMAGE instead of process.execPath so the host wrapper script gets re-executed — see app:afterUpdate in pear-chat.

The two-event split is what lets you build UI like the "Update ready!" banner in Reshape into a production app: show a spinner on updating, swap to a restart button on updated, restart the app on click.

Stage, provision, multisig

• Stage — Local and team checks: feature branches, unsigned or lightly signed builds, ephemeral links. Appends to the application drive; good for iteration.
• Provision — Prerelease / QA / dogfood: synchronizes from a versioned stage source onto a target link while compacting additions and deletions so the drive is closer to what stakeholders mirror.
• Multisig — Production: writes require co-signing up to a configured quorum so one compromised machine cannot redefine the release line.

Each stage link can feed the next operation; a provisioned link becomes the source for multisig commits once signers agree.

Deployment directory and release lines

A deployment directory is the multi-architecture output you assemble after per-OS make steps (often with pear build merging darwin, linux, and win32 artifacts). That directory is what pear stage reads from disk and writes into Hypercore-backed storage for a given release line link.

Release lines are parallel stability tracks: common names are development, staging, rc (each a staged link), then prerelease (provisioned from rc), then production (multisig’d from prerelease). The upgrade field in package.json decides which link a shipped binary follows for OTA — so different builds can track different lines intentionally.

A common pattern is that rc’s upgrade pins the production multisig key, so rc builds do not receive casual OTA bumps — you ship new installers when that line moves.

Release cycle (steady state)

Once bootstrapping finishes, the steady release cycle is repetitive: bump version, make per platform, build the deployment directory, stage, iterate; when stable, provision; when assessed, run multisig prepare → sign → verify → commit; production goes live; the next cycle starts again at version.

Numbered labels align with common documentation ordering (touch/seed and upgrade-link setup happen before this loop is warm).

Foundational steps (bootstrap + loop)

The foundational diagram adds multisig key creation and config beside the main loop: signing keys, multisig.json, pointing upgrade at the multisig link, then joining the same release flow.

Stage-only is enough for proofs of concept; production benefits from quorum signing and machine-independent drives.

From per-OS builds to one directory

That directory must at least contain package.json and by-arch/.../app trees before pear stage is meaningful.

Multisig setup and signing

The diagrams below follow hello-pear-electron's Foundational Steps — the same Electron + Bare worker template Keet and PearPass ship. One-time multisig wiring is in Set up multisig; every production shipment after that uses Sign with multisig. If a commit fails mid-flight, see Troubleshoot multisig.

How setup connects to the release cycle

multisig.json points at the provision drive (srcKey) from the most recent hello-pear-electron pear stage / pear provision. Shipped binaries read the multisig link from package.json upgrade.

Quorum signing

Each production commit runs the four steps in Sign with multisig: hyper-multisig request, hypercore-sign from each signer until quorum is met, hyper-multisig verify, then hyper-multisig commit.

Release lines

For hello-pear-electron, one pear build output can feed parallel stage links; prerelease and production are the provision and multisig gates on the trust ladder.

Custom lines are optional forks for spikes, hotfixes, or instrumented builds — same mechanics, different seeded link.

Relationship to Pear’s global storage story

Platform installs still use Pear’s OS-wide tree described in Storage and distribution. The diagrams here are about application release artifacts moving between links — not replacing that global layout.

Glossary

Terms you will see across the Pear desktop release and OTA update docs:

Where to go next

• Pear desktop application architecture — workers, storage, and update events in the running app.
• Deploy your application — operator checklist for pear stage / pear provision / multisig tooling.
• Build desktop distributables — per-OS makes and signing pointers.
• Desktop release npm scripts — common package.json scripts.
• Troubleshoot desktop releases — OTA, staging, and pear build pitfalls.