Build and Deploy
The git push that becomes a release, the build that runs in isolation and migrates on a clone rather than live, and the atomic pointer swap that promotes it to live.
A push to an app's default branch becomes the live release. Nothing else does. This chapter follows that push from the git server through the compilers to the atomic promotion, and covers previews, rollback, and what happens after a deploy.
#From Push to Release Rows
The git role receives the push, makes it durable in S3, and runs its post-receive step. See Git Hosting. Post-receive records which refs moved and creates a release row per pushed branch: a default-branch push creates a release that will be promoted; any other branch creates a release that will become a preview. The default branch is always built, and the fan-out of one push is capped, so a push of many branches cannot start an unbounded number of builds. A newer push to the same branch retires the builds it supersedes: a build still waiting on a job runner is cancelled at its next checkpoint, and a build past that point finds its transitions refused and never promotes. A push, a rebuild and the automatic retry of an interrupted build all start a build through the same path, and a retry is skipped when a newer build of its branch exists.
A release row is the unit of everything downstream: it has a status, a build log with timestamped phases, the commit it was built from, and the manifest as read from that commit.
#The Compile
Compilation runs in the platform and delegates the two heavy steps to job runners on the jobs island. See Job Runners.
- Read and validate the manifest. Methods, tables, roles, interfaces, jewels, data source mappers and readers. Validation errors fail the build here, with the message the builder needs.
- Compile methods. The method compiler bundles each method to JavaScript, resolves the release's dependencies inside a worker-derived image, and builds the dependency artifact: a
node_modulestarball with an ABI stamp. Outputs upload through presigned grants to the release's prefix in S3. - Compile the web interface. When the app has one, the web build runner runs the interface's own build with the asset base pointed at the release-addressed static origin, and uploads the output. Mounted child apps and web routing are validated alongside.
- Compile the other interfaces. API, MCP, cron, webhook, email, agent and voice interfaces are compiled to exactly what their surfaces read at request time, and every reference is checked against what the release declares, so a typo fails the build rather than a session. The cron schedule and the jewel identity are recorded for promotion to apply. Every other surface reads its config from the release answering a request, so it has nothing to apply.
- Diff the tables. Table definitions are parsed from their TypeScript, and the result is diffed against the live database's recorded schema. The platform confirms the recorded schema agrees with the live file before trusting the diff, so a misplaced file fails with the missing tables named rather than producing a phantom migration.
- Apply the schema change to a clone. When the diff is not empty, the platform clones the live database file to a staging copy and applies the change there. Adds, drops and constraint changes that a plain alter cannot express are performed by rebuilding the table through a copy. A failed migration leaves live untouched and marks the release failed.
The release is now compiled. Its logs, artifacts and staged database exist; nothing is serving from it yet.
#Promotion
For a default-branch release, promotion applies what the build computed, in an order chosen so that a failure anywhere before the pointer swap leaves live serving exactly as it was:
- The tables diff is applied to a fresh clone of live, so the promoted database reflects writes that landed during the build. Live's database is flushed before the clone, and live SQL is held from the clone until the pointer swap, so no write lands in the copy being left behind. When auth is enabled, the sync triggers that mirror the app's users table are installed. This is the step most likely to fail, and its output is keyed by the new release, so it touches nothing live.
- The jewel identity is applied: the app's jewel user and its roles, and its row in the new database's users table.
- The app's live pointer is swapped to this release in one transaction, which marks the previous live release superseded. The swap runs under a lock on the app, and the pointer only moves forward: if a newer release on the same branch is already live, or this release was retired while it promoted, it is marked superseded and the pointer is left alone.
- The cron registry is reconciled against the release's schedule, right after the swap, so it only ever matches a release that went live.
- After the swap, on a best-effort basis and unable to fail the deploy (a cron failure included, which the build log reports): the rehearsal copy is deleted, caches are invalidated, and the previous release's sandboxes are stopped by app label, so the next request claims a sandbox configured for the new release.
- An audit event records the deploy, and the workspace's changelog gains an entry from the commit messages.
The cutover is the pointer swap. Requests in flight finish on the release they started on; the next request resolves the new one.
#Previews
A non-default-branch release is set to preview instead of promoted. It is served on a gated host whose label contains a double hyphen, in two forms: an immutable release-addressed one and a stable branch alias. Its data plane is a clone keyed by its own release id, so it never reads or writes live. Workspace members reach it with their session; anyone else needs a share link the workspace issues. See Environments.
#After the Deploy
Post-deploy effects run after promotion or preview. Each runs independently, each records its start and its result in the release's build log under its own phase, and none can fail the deploy or each other. An effect that hands its work off, such as the diagnostics audit or the report, records its result when that work ends:
- Frontend diagnostics. A headless-browser audit of the built interface, run on the jobs island, with results in the dashboard.
- Data source mappers. Each declared source is pointed at the release's compiled mapper, so a changed or new mapper takes over new ingestion when the release goes live. A reader needs no such step: it always runs against the live release, and before promotion the build counts what each reader has not yet read, which the CLI's release wait command reports.
- The assessment report. A static analysis of the release: its auth methods, its data handling, and the models and data it sends. It is regenerated behind a commit classifier, so an unchanged release reuses the prior report. When the report has run, the CAIQ attestation is filled from it and the platform's cited facts. See Compliance and Attestation.
- Mirrors. The app's overview, roadmap and pitch material, when it declares them.
#Rollback
A release is immutable, and its database file is left in place when it is superseded, but nothing moves the pointer back to it. Rolling back is a revert and push, which builds a new release through the same pipeline, from the current live data. The migration it runs follows the same rules as any other: added, dropped and retyped columns and changed unique constraints rebuild the table by copy, and a rename is a drop and an add, so its data does not carry over.
#Development
Between pushes, a builder works in a dev environment: their dev box, with their own dev database cloned from live. Saving a table definition syncs the change to the dev database with the same migration rules as production. The editor can reset the dev database from live, truncate it, or lift data between dev and live. Method edits take effect on the next invocation, with per-request transpilation. See Dev Boxes.
``` Figure 16, "Build and Deploy": a left-to-right pipeline. Along the spine: a git push reaches the Git role, which makes the push durable in S3 and runs post-receive to create a release in the building state. The release is built in isolation: manifest validation, then the method compiler on the jobs island (bundles and the dependency artifact), the web build on the jobs island, the other interface compilers (API, MCP, cron, webhook, email, agent, voice, jewels), a table diff, and the schema change applied to a clone of the live database, so live is untouched if the migration fails. The release is then compiled. At the compiled release a branch decision forks the flow. A default-branch release continues along the spine to Promote: the tables applied to a fresh clone, the jewel identity, the atomic forward-only swap of the live pointer that supersedes the old release, the cron reconcile, stopping the previous release's sandboxes, and an audit event. The app is then LIVE. Any other branch drops to Preview, served on a gated host against its own cloned data plane. After either path, post-deploy effects run in parallel and in isolation, none able to fail the deploy: frontend diagnostics, data-source mappers, the assessment report (followed by the CAIQ attestation), and the app's mirrors. A side box shows rollback: a revert and push re-enters the same pipeline and builds a new release. No trust boundary is drawn in this figure, so there is no crimson.