Deployments

Why release tracking lives here

The commercial contract already knows every instance, the customer it belongs to, and what that customer is entitled to. Release tracking adds the other half of the same fact: which versions of your product each instance runs. Kaiten keeps both halves in one model, so a question such as "Sakura Tokyo's License grants delivery tracking — does its instance run the release that ships it?" is answered by reading one set of records, with the same slugs on both sides.

Most stacks hold this knowledge in several places: the delivery pipeline knows what was shipped, an inventory knows which customer runs where, and the commercial system knows what was sold. Putting what runs where beside who bought what makes the separate inventory redundant. It does not move the pipeline: your CI/CD, registries, and runners keep shipping the artifacts; Kaiten records the landing and exposes it to the contract, to targeting rules, and to the audit trail.

The four entities

Component — one building block of your product at one version: name plus version, unique together within your organization. Successive versions chain through previousComponentId, so Delivery Service 0.9.0 → 1.0.0 is two components linked into one history. A component that no release has bundled yet can be edited in place; once a release bundles it, edits produce the next version instead.

Release — a versioned bundle of components, the shippable unit. Its component list is fixed at creation and there is no update endpoint: Kaiten Sushi Shop's 2026.8.0, the release that introduces real-time delivery tracking, bundles API and Web App at 2026.8.0, Kitchen Display 1.2.0, and Delivery Service 1.0.0, and it will bundle exactly those four for as long as it exists.

Deployment zone — a logical execution environment where instances run, shared by many customers' instances or dedicated to one. Kaiten Sushi Shop runs shared-eu, shared-apac, and sakura-dedicated, all three production zones; a dedicated metadata field says which one serves a single customer. A zone points at the release it currently runs (releaseId), carries typed metadata, and is what an instance optionally attaches to — the instance runs whatever its zone runs.

Deployment — the append-only journal. Every time a zone's current release changes, one entry is appended: the release, the zone, the moment, the actor. Entries are never edited, and are removed only with their zone, so the journal is the history of every zone and of every release. Kaiten Sushi Shop's journal reads as a progressive rollout: 2026.7.0 in all three zones, then, about five weeks later, 2026.8.0 in shared-eu and shared-apac — while sakura-dedicated still runs 2026.7.0.

How it works

1. Register components as your product's building blocks ship — POST /components, one entry per version, chained to the previous one.
2. Cut a release that bundles the component versions you are shipping together — POST /releases with their ids. From this point the bundle is a fact.
3. Model your zones — POST /deployment-zones for each place instances run, with its environment class as type and the metadata your organization declared.
4. Record each landing by pointing the zone at the release — PUT /deployment-zones/{slug} with the new releaseId. Kaiten appends the journal entry and emits RELEASE_DEPLOYED.
5. Attach instances to zones at creation or later. What an instance runs is then derived from its zone, and targeting rules can read the zone an instance runs in.

In this section

API endpoints overview

Scopes follow the module: read:components / write:components, read:releases / write:releases, read:deployment_zones / write:deployment_zones; the instance linkage uses write:instances. See scopes.

Components

Releases

Deployment zones

Instance linkage

Events

The event catalog lists every event with its payload; events and webhooks explains the two delivery paths.

Where to go next

The one-screen version of this pillar is the concept page Releases & Deployments. Exact reference — tables, columns, constraints: the releases and deployments section of the data model.