Deployments

View as Markdown

Deployments

Persist pipelines server-side and run them on a schedule. Accessed via client.deploy; full method tables in the API reference.

Teams as environments

deploy.add snapshots a pipeline as an immutable, sha256-locked artifact version in the org registry; deploy.deploy points a team (the environment — Staging, Production, …) at a version. Promotion and rollback are the same pointer move. Deploy targets are always explicit — there is no default-team fallback. Every registry add and pointer change lands in an immutable audit history (deploy.history, rows carry seq as the stable append-order identity).

const result = await client.deploy.add({ pipeline: myPipeline, comment: 'v2 prompt fix' });
await client.deploy.deploy('proj-1', result.artifact.version, 'team-staging');
await client.deploy.setSchedule('proj-1', 'webhook_1', '*/15 * * * *', 'team-staging');

// Promote the same version to Production later — the identical gesture.
await client.deploy.deploy('proj-1', result.artifact.version, 'team-prod');

const live = await client.deploy.list();
for (const dep of live.rows) {
	console.log(dep.teamId, dep.projectId, 'v', dep.version, dep.state);
}

add({ pipeline, deployTo }) collapses add + deploy into one step. Listings (deploy.list, deploy.versions, deploy.history) return the standard { rows, total, page, pageSize } envelope, server-paged. deploy.artifact(projectId, version) fetches one immutable version's pipeline JSON, sha256-verified server-side.

Schedules

deploy.setSchedule(projectId, sourceId, schedule, teamId, options?) sets (or clears with null/'manual') one source's 5-field cron schedule. pauseSchedule/resumeSchedule stop and restart a single source's firing without touching its cron. deploy.preview(schedule, count?) is the single cron evaluator — validity plus next occurrences; never parse cron client-side.

Scheduled runs execute as the team (no stored user credential); their logs land in the team's run-log continuum, readable by teammates via client.log with teamId. deploy.run(projectId, sourceId, teamId) triggers one deployed source now — the same trusted, actor-free team dispatch the scheduler uses — returning { token, version }, and deploy.setSourceConfig sets per-source execution settings for deploy runs (traceLevel, debugOut).

States

State	Meaning
enabled	Schedules fire per cron.
disabled	The kill switch (deploy.disable) — nothing runs until enabled again.
errored	A scheduled dispatch failed — on permissions, or on an unusable artifact (missing or sha256-tampered) — and the scheduler stopped retrying.
removed	Soft delete (deploy.remove): hidden from listings, history and artifacts survive; re-deploying revives it.

Permissions

Mutations require task.control on the TARGET team. Reads follow the visibility model: an org admin sees every team and every personal space; a user sees their own personal space and the teams they are a member of.

App publish ladder

Typed wrappers over rrext_deploy_app — the publish ladder for RocketRide apps. Deploy copies code to the server as the next immutable registry version (deploy.add); a deployment carries the review lifecycle in its own state (private → submit → ready | rejected). Publish binds a deployment to an audience — @me, @team/<name>, or @public — as a pure pointer (@user is a legacy input alias for @me, never displayed); repointing it covers first publish, update, promote, and rollback alike.

The review state lives on the deployment, not the binding: an app deploys private (internal-eligible), the developer submits it for review, an admin approves (ready) or rejects (rejected). A @public binding may only point at a ready deployment; @me/@team bindings accept any internal-eligible (not failed) deployment. So there is no separate "publish-and-wait" — public listing is: submit → approve → repoint the public pointer.

App ids are partitioned by the caller org's developer id: every app is <developerId>.<name> (globally unique), so an org can only deploy/publish ids inside its own namespace — the platform holds rocketride. Deploying or publishing an app requires the org to have claimed a developer id.

deploy.add and deploy.addApp live on client.deploy; every other verb below is a method on the client itself (client.listDeployments(...), client.publishApp(...)), not on client.deploy.

Method	Description
deploy.add	The ONE rail door: deploy any kind of object as the next immutable registry version. kind:'pipe' (default) takes a pipeline dict; kind:'app' takes ONE data zip of the app's SOURCE — the server performs the build (client-produced binaries are never trusted); the zip is retained and unpacked at receipt, born deployment-state private. The app id must be inside your developer namespace.
deploy.addApp	Pack an app folder's source and deploy it as the next registry version — the one call behind the App Builder's Deploy button and CI scripts. Packs by the App Builder rules (workspace-rooted zip, appManifest.include, hierarchical gitignore + the hard node_modules/dist/.git baseline, symlink containment, 50MB zipped / 512MB uncompressed caps); onProgress receives one line per step. Deploying activates nothing — bind an audience with publishApp afterwards.
deploy.verifyApp	The no-side-effect precheck for addApp — purely local, no server call: manifest shape and id grammar, declared icon/README assets, appManifest.include entries, and a pack dry run against the size caps. Server-side concerns (the build, store review) are out of scope.
listDeployments	The version rail, newest first — the developer org sees its FULL rail (published or not), other callers only their visible versions. Each entry carries its deployment state, its buildStatus ('ok' = servable), and the rungs naming the audiences bound to it.
submitApp	Submit a deployed version for store review — flips the deployment private → submit (it enters the admin queue). Developer-org + namespace gated.
withdrawApp	Withdraw a pending review — the developer's own cancel: flips the deployment submit → private (leaves the admin queue, back to draft; history records withdrawn). Only a version in submit withdraws. Developer-org + namespace gated.
replyApp	Append a developer message to the app's review thread — the developer half of the reviewer conversation. Rides deployment_history as a reply row (side 'developer'), the same stream deploy.history() reads. Developer-org + namespace gated.
buildLog	One version's durable server build log — the full phase-by-phase output the build worker stores beside the version's artifacts (no error text rides the rail rows). Long logs serve their tail; '' = no log. Developer-org gated.
publishApp	Bind a deployment to '@me', '@team/', or '@public' ('@user' = legacy input alias). The binding is a pure pointer born 'enabled'. @public requires the deployment be ready (approved); @me/@team accept any non-failed deployment. Pinning ANOTHER org's public app to '@me'/'@team' is the version selector and is allowed; publishing your own app requires the id to be in your namespace.
whereApp	The reverse index: {rung, handle, version, appVersion, state, deployedAt} per audience — state is the bound DEPLOYMENT's review state.

Serving needs no verb: a version's bundle loads from the stable /apps/<appId>/v<N>/remoteEntry.js URL constructed from its registry version number, with entitlement enforced by the serve route on every request (registry ints ONLY — semver is display).

Full signatures: API reference.

See the Shell API guide for the app model itself.