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
runtimeVersionequals 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:
| Status | Meaning |
|---|---|
| Draft | Created, no artifacts yet |
| Uploading | Waiting for artifacts |
| Processing | The server is verifying bytes and signing |
| Ready | Every platform has a verified, signed artifact. Deployable |
| Deploying | A deployment or staged rollout is in progress |
| Active | A channel is actually serving it |
| Failed | Verification failed |
| Rolled back | Was served, then replaced by a rollback |
| Archived | Retired; 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
Pendingand only becomesSucceededwhen 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.