Skip to content

docs(cloud-deployment): foreground os package publish; mark os publish legacy#1689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 1 commit into from
Jun 10, 2026
Merged

docs(cloud-deployment): foreground os package publish; mark os publish legacy #1689

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 23 additions & 21 deletions content/docs/guides/cloud-deployment.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -62,31 +62,33 @@ or the host's deployment config.

## Cloud-managed deployment

When targeting Cloud, publish metadata to an environment:
The unified path publishes a **versioned package** and installs it into a cloud
environment in one step:

```bash
OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os publish
os cloud login # once: stores a cloud token
os package publish --env env_prod --install # publish a version + install it
```

The CLI posts compiled metadata to:

```text
POST /api/v1/cloud/environments/:environment/metadata
```

Rollback activates an earlier revision:

```text
POST /api/v1/cloud/environments/:environment/revisions/:commit/activate
```

Package publishing uses the package registry endpoints:

```bash
os package publish --env env_prod
```
This registers a `sys_package` plus an immutable, checksummed
`sys_package_version`, then records the install against the target environment
(see the cloud [package](/docs/references/cloud/package) and
[package-version](/docs/references/cloud/package-version) references). The
environment kernel is evicted on install, so the new metadata and any sample
data are live on the next request — no restart.

> **Legacy env-revision path.** `os publish` posts compiled metadata straight to
> an environment as a revision, rather than as a versioned package:
>
> ```bash
> OS_CLOUD_URL=https://cloud.example.com OS_ENVIRONMENT_ID=env_prod os publish
> # POST /api/v1/cloud/environments/:environment/metadata
> # rollback: POST /api/v1/cloud/environments/:environment/revisions/:commit/activate
> ```
>
> It still works, but the package flow above is the direction of travel
> (ADR-0006 v4): `sys_environment_revision` is retired once all publishes go
> through the package endpoints.

Cloud control-plane hosts, database provisioning, billing, and public SaaS
deployment are outside this framework repository. The framework runtime exposes
Expand Down