Release Management & Distribution
A release is a named, versioned snapshot of your SaaS package: the exact configuration state your product is in at the moment you cut it. Today you cut releases, compare them, review them in a typed comment trail, and run the release compliance check. Approving a release, deploying it to your environments and tenants, staged rollout, and rollback are not available yet. The same area also covers desktop distribution: publishing signed, auto-updating builds of your product that installed clients pull from your own update channels.
Pro Release management and distribution are part of the SaaS Builder, included with Backbuild Pro. See pricing.
Two layers of shipping
The SaaS Builder gives you two complementary shipping mechanisms:
- Configuration releases. Capture your configuration as a versioned release, compare versions, and review each one. Moving a release through your environments to your tenants is coming soon.
- Desktop / app distribution. Publish downloadable,
cryptographically signed builds of your product (per OS and architecture)
onto named channels such as
stableorbeta, and let installed clients check for and pull the right update. This governs the binaries your end users install.
The first half of this page covers configuration releases; the second half covers desktop distribution.
The release lifecycle
Every release has a status. You create a release as a draft and
advance it as it is reviewed.
| Status | Meaning | Available today |
|---|---|---|
draft | Freshly created. The captured configuration is frozen in the release. | Yes |
testing | Under review. | Yes, from draft |
rejected | Failed review. A reason is required. | Yes, from testing |
archived | Retired. Kept for history and diffing. | Yes |
approved | Signed off and cleared to deploy. | Not available yet |
Comments, compliance & diffs
Releases are collaborative. You can attach threaded
comments to a release (typed as
general, bug, test_pass,
test_fail, approval, rejection, or
task) to keep test results and decisions next to the release they
concern. You can diff two releases to see exactly what changed
in the captured configuration between them, and list a release’s
items, the version-pinned manifest of exactly what
configuration it contains.
You can also run the compliance check against a target environment. Release approval is not available yet, so the check’s approval step reports failed and a release does not pass today; the other checks still show what a release is missing, such as a data bundle or an application configuration. The checks are described in Release Management.
Coming soon: approval, deployment, and rollout
The following are not available yet. This is how they will work:
- Approval. A release will be approved for each environment by the people your approval policy names, and approvers will not be able to approve their own release.
- Deployment in order. A release will deploy to development, staging, preprod, and production in that order, and production will serve your paying tenants.
- Rollout strategies. A production deploy will reach tenants immediately, by a list of named tenants, by a percentage, or through scheduled stages, and a rollout will pause, advance, or cancel on demand.
- Rollback and undeploy. An environment will return to its previous release, or a release will be removed from an environment.
- Import to draft. A shipped release will load back into a fresh draft for the next round of work.
Desktop & app distribution
Beyond configuration releases, the distribution layer publishes signed, downloadable builds of your product and serves auto-update information to installed clients. The model is: a product has many versions; each version carries one or more artefacts (one per OS / architecture); versions live on named channels; and clients query the current version for their channel to know whether to update.
Publishing a version
Publishing is a staged, integrity-checked pipeline so a half-uploaded build is never served:
- Register / update the product (by slug): its display name, branding, optional custom domain, and data residency (
usoreu). - Start a version: declare the version string and the channel it targets. This opens a staged version you add artefacts to.
- Add artefacts: one per OS/architecture, each with its storage key, archive format,
sha256hash, size, and any OS-specific signature metadata. - Complete: attach release-notes URL, minimum supported OS, and whether the update is a required upgrade.
- Finalize: submit the signed manifest (its
sha256and Ed25519 signature). Finalizing makes the version eligible to serve.
You can cancel a still-staged version before it is finalized. The hashes and the signed manifest are what let clients verify that what they downloaded is exactly what you published.
Channels, promotion, rollout & yanking
- Promote a version from one channel to another (e.g. move a
betabuild tostable) without re-uploading artefacts. - Set a rollout percentage on a published version so only a fraction of clients on that channel are offered it: a staged desktop rollout.
- Yank a version to immediately stop offering it (e.g. a regression slipped through), with a recorded reason.
Signing keys
Update integrity rests on a published signing-key chain. You register Ed25519 signing keys (and may chain a successor key signed by its predecessor for rotation), and revoke a key with a reason when it should no longer be trusted. Installed clients fetch the public key chain to validate every manifest they receive.
What clients call (public)
Installed apps are anonymous, so the update-check endpoints are public and
require an explicit org_id (the client cannot be inferred). They
return only public-safe fields:
- The current version for a product on a channel; the client passes its current version and an optional install identifier so you can honor staged rollout percentages.
- The public signing-key chain, so the client can verify the manifest signature before installing.
API reference
Unless marked public, every endpoint requires an authenticated
session and the relevant release or distribution permission (organization
owners and admins hold these by default). The owning organization is resolved
from your session. {packageId} is the SaaS package,
{releaseId} a release within it,
{rolloutId} a rollout plan, and {slug}
a distribution product slug. Successful reads and writes return a
{ "success": true, "data": ... } envelope.
Releases
| Method & path | Description |
|---|---|
POST /v1/saas-packages/{packageId}/releases | Create a release (captures current configuration). Body: release_name (required), release_notes. |
GET /v1/saas-packages/{packageId}/releases | List releases. Query: status, page, limit. |
GET /v1/saas-packages/{packageId}/releases/{releaseId} | Get a single release. |
PATCH /v1/saas-packages/{packageId}/releases/{releaseId}/status | Update status: testing, rejected (with a reason), or archived. approved is not available yet. |
GET /v1/saas-packages/{packageId}/releases/diff?from={id}&to={id} | Diff two releases. |
GET /v1/saas-packages/{packageId}/releases/{releaseId}/items | List the version-pinned manifest items in a release. |
Deployment (coming soon)
These endpoints become usable when deployment is available.
| Method & path | Description |
|---|---|
POST /v1/saas-packages/{packageId}/releases/{releaseId}/deploy | Deploy to an environment. Body: environment (required), rollout_strategy, target_org_ids, target_percentage, rollout_stages, notes. |
POST /v1/saas-packages/{packageId}/releases/{releaseId}/rollback | Roll an environment back to its previous release. Body: environment (staging/preprod/production), notes. |
POST /v1/saas-packages/{packageId}/releases/{releaseId}/undeploy | Remove the active deployment from an environment. Body: environment, notes. |
GET /v1/saas-packages/{packageId}/environments | Current deployment status per environment. |
GET /v1/saas-packages/{packageId}/environments/history | Deployment history. Query: environment, page, limit. |
Approval policies & workflow (coming soon)
These endpoints become usable when release approval is available.
| Method & path | Description |
|---|---|
POST, GET /v1/saas-packages/{packageId}/approval-policies | Create or list approval policies for the package. |
GET, PATCH, DELETE /v1/saas-packages/{packageId}/approval-policies/{policyId} | Read, update, or deactivate a policy. |
POST /v1/saas-packages/{packageId}/gates, POST .../gates/recompute | Bind a policy to a step between two environments, and reconcile the steps. |
POST /v1/saas-packages/{packageId}/releases/{releaseId}/request-approval | Request approval for a step. |
POST .../releases/{releaseId}/approve, POST .../reject | Record an approval or a rejection (a rejection requires a reason). |
GET .../releases/{releaseId}/gate-status | Evaluate where a step stands against its policy. |
POST .../releases/{releaseId}/promote | Promote a release across a step. |
Comments & compliance
| Method & path | Description |
|---|---|
POST /v1/saas-packages/{packageId}/releases/{releaseId}/comments | Add a comment. Body: content, optional comment_type, environment, parent_comment_id. |
GET /v1/saas-packages/{packageId}/releases/{releaseId}/comments | List comments. Query: environment, comment_type, page, limit. |
POST /v1/saas-packages/{packageId}/releases/{releaseId}/compliance-check | Run a compliance check. Body: target_environment. |
Rollouts (coming soon)
These endpoints become usable when deployment is available.
| Method & path | Description |
|---|---|
POST /v1/saas-packages/{packageId}/rollouts | Create a rollout plan for an active deployment. Body: deployment_id, strategy, and the matching target_org_ids/target_percentage/stages. |
GET /v1/saas-packages/{packageId}/rollouts/{rolloutId} | Get rollout status with per-stage progress. |
POST /v1/saas-packages/{packageId}/rollouts/{rolloutId}/advance | Advance a progressive rollout to its next stage. |
POST /v1/saas-packages/{packageId}/rollouts/{rolloutId}/pause | Pause a rollout. Optional body: reason. |
POST /v1/saas-packages/{packageId}/rollouts/{rolloutId}/cancel | Cancel a rollout. Optional body: reason. |
Desktop / app distribution
| Method & path | Description |
|---|---|
PUT /v1/releases/products/{slug} | Register or update a distribution product. Body: base_tool, display_name, optional branding_config_id, custom_domain, data_residency. |
POST /v1/releases/products/{slug}/versions | Start a new version. Body: version, optional channel. |
POST /v1/releases/versions/{id}/artefacts | Add an OS/arch artefact. Body: os, arch, r2_key, archive_format, sha256_hex, size_bytes, optional os_signature. |
POST /v1/releases/versions/{id}/complete | Attach metadata. Body: optional release_notes_url, min_supported_os, required_upgrade. |
POST /v1/releases/versions/{id}/finalize | Submit the signed manifest. Body: manifest_sha256_hex, manifest_sig_hex. |
DELETE /v1/releases/versions/{id} | Cancel a still-staged version. |
POST /v1/releases/products/{slug}/channels/{channel}/promote | Promote a version to a target channel. Body: version, target_channel. |
PATCH /v1/releases/versions/{id}/rollout | Set rollout percentage. Body: product_slug, version, percentage (0 to 100). |
POST /v1/releases/versions/{id}/yank | Yank a version. Body: product_slug, version, reason. |
POST /v1/releases/signing-keys | Register a signing key. Body: key_id, public_key_hex, optional signed_by_key_id, successor_signature_hex. |
POST /v1/releases/signing-keys/{id}/revoke | Revoke a signing key. Body: reason. |
Update-check endpoints (public, no auth)
| Method & path | Description |
|---|---|
GET /v1/releases/{slug}/current?org_id={id} | Current version for a product on a channel. Query: org_id (required), optional channel, current_version, install_id_hash. |
GET /v1/releases/signing-keys/chain?org_id={id} | Public signing-key chain for manifest verification. Query: org_id (required). |
Related
- SaaS Packages: the product a release captures
- Store & App Distribution: store accounts, listings, and submissions
- Tenants: the customers a release ships to
- SaaS Builder overview
Frequently asked questions
- Can I ship a release to my tenants today?
- Not yet. You can cut, compare, review, and compliance-check releases today; approval, deployment, rollout, and rollback are coming soon.
- Can I see what changed between two versions?
- Yes. Diff any two releases of a package to see what was added, changed, and removed, and list a release's pinned items to see exactly what it contains.
- Why does my release fail the compliance check?
- Release approval is not available yet, so the approval step fails for every release. The other checks show what the release itself is missing.