Markdown

Concepts

Organizations, workspaces, projects

An organization is the tenant boundary: members, roles, billing and audit log live there. Workspaces group projects inside it. A project is one application.

Roles are Owner, Admin, Developer and Viewer. A *project membership* can raise a person's role for one project (never lower it).

Runtime version

The runtime version is the compatibility key between a release and an installed binary. You set it; Stacklift enforces it:

  • a device only receives a release whose runtimeVersion equals the one it reports;
  • a rollback is refused across runtime versions;
  • bump it whenever native code, native modules, permissions or the JS engine change.

Releases

A release is a version plus verified artifacts. Statuses:

StatusMeaning
DraftCreated, no artifacts yet
UploadingWaiting for artifacts
ProcessingThe server is verifying bytes and signing
ReadyEvery platform has a verified, signed artifact. Deployable
DeployingA deployment or staged rollout is in progress
ActiveA channel is actually serving it
FailedVerification failed
Rolled backWas served, then replaced by a rollback
ArchivedRetired; read-only

A release can carry more than one artifact per platform, as long as the kinds differ: for example a script-bundle (rules in JavaScript) and a ui-layout (a server-driven screen layout) together. Each SDK asks for the kind it handles.

Transitions are enforced in one place (@stacklift/shared), with row-level locks so concurrent operations can't interleave.

Channels and environments

Channels (production, staging, development, beta, or your own) are what devices subscribe to. A channel points at exactly one release at a time. Environments label where a build is meant to run and can be attached to channels and releases.

A channel serves one release. If you deploy a release with a different runtime version, devices on the old runtime stop receiving updates from that channel. The dashboard and CLI warn before you do it.

Deployments, rollouts, rollbacks

  • A deployment records the intent to point a channel at a release. It starts Pending and only becomes Succeeded when the engine has switched the channel in a transaction.
  • A rollout is a deployment below 100%. Devices are bucketed by sha256(rolloutId : deviceId) mod 100; a device is in the cohort when its bucket is below the percentage. Raising the percentage only adds devices. Cancelling returns the cohort to the baseline release.
  • A rollback points the channel back at an earlier compatible release, cancels any in-flight rollout on it and records the reason.

Update checks

The delivery plane answers one question: *which release should this device run?* It considers the channel, the active rollout cohort, the runtime version, the platform, the artifact kind the SDK asks for (optional) and whether a verified deliverable artifact exists. Native binaries (native-binary, i.e. store builds) and container image references are never offered as updates — store builds are *recorded* by the CLI without being uploaded, see Store releases; desktop installers (desktop-installer) are, because the installer is the update mechanism on desktop — see Desktop apps.