Environments follow channels

Point an environment at a release channel, and it deploys itself every time that channel moves. Nobody runs a deploy command, and nothing in the path calls back into CI.

You already publish to channels: a merge to main publishes your projects and advances a channel, a promotion moves a channel to an existing release set. This page makes an environment react to that move — it redeploys the workloads whose content changed, and leaves the rest alone.

Declare a following environment

Add an envs entry to putnami.ci.json. The environment names the channel it follows and lists the workloads it owns:

{
  "envs": {
    "prod": {
      "channel": "canary",
      "workloads": [
        { "select": ["apps/web-api", "apps/worker"] }
      ]
    }
  }
}
Field Meaning
channel the channel this environment follows. Without one, the environment only deploys when you ask it to.
workloads[].select the exact workload projects this environment runs. A workload no rule selects is not part of the environment.
workloads[].channel overrides the channel for those workloads. An environment whose workloads end up on different channels is not deployed by a move — see Not yet supported.

Selectors are exact project paths. The environment key is a plain name such as prod or staging.

The control plane reads this file from your connected repository at an exact commit and accepts it as a numbered revision. Connect the repository first with putnami cloud source connect --repo <owner>/<repo>. A move deploys against the accepted revision, so an environment the control plane has not accepted yet follows nothing.

Before the first deploy

Run the preflight from the workspace root before you merge the change that turns an environment on:

putnami cloud env doctor prod

It checks every prerequisite continuous delivery needs and prints one check per prerequisite. It changes nothing: it reads files in your checkout and makes one read request to the control plane. Without an environment name, it checks the environment your workspace link names, then prod.

env doctor prod  failing  8 of 11 prerequisites ok, 1 missing, 2 could not be checked

  METRIC                   VALUE          WINDOW
  prerequisites ok         8 of 11 (73%)  now
  prerequisites missing    1              now
  prerequisites unchecked  2              now

  STATE    CHECK                         DETAIL
  ok       put-binding                   active put namespace acme
  failing  oci-registry                  putnami.workspace.json names no registries.oci.publish with a host and a namespace
                                         fix: set in putnami.workspace.json: "registries": {"oci": {"publish": "oci.putnami.dev/acme"}}
  …

Each check reads ok, failing, degraded, or unknown:

  • failing means the prerequisite is missing. The check prints the exact fix.
  • degraded means the prerequisite exists but is stale. The check prints the exact fix.
  • unknown means the check could not run. The detail says why, and the check still prints the fix.

The header and the metrics count both. The command exits 1 when a prerequisite is missing, and 0 otherwise. A degraded or unknown check, including every control-plane check when the control plane does not answer, fails the command only when you pass --strict. Exit 0 therefore does not mean that every prerequisite was checked: read the header, or the prerequisites_unchecked metric in structured output.

Check Checks
put-binding The workspace has an active put namespace binding.
oci-registry putnami.workspace.json sets registries.oci.publish to a host and a namespace, such as oci.putnami.dev/acme.
oci-binding The workspace has an active oci namespace binding, or it holds at least one active OCI publisher package share from the workspace that owns the namespace its images publish into.
environment-definition The control plane accepted an environment definition that declares this environment, and its workloads and channel match putnami.ci.json at the head of your default branch. When they differ, the check reads degraded, names each difference, and prints putnami cloud env enable <env> as the fix. When the control plane cannot read the head, the check stays ok and the detail says it was not compared.
ci-envs putnami.ci.json declares the environment with exact workload paths, each with a putnami.json, and sets distribution.memberAttribution to true.
publish-namespaces Each selected workload with a Config schema declares a @putnami/cloud:publish-config namespace, and each one whose build produced a migration bundle declares a @putnami/cloud:publish-migration namespace.
runtime-operation-grants Runtime lets the control plane's callers run operations in this workspace.
runtime-binding-grant-config Runtime lets config-api use its binding in this workspace.
database-ownership In each database a selected workload migrates, the <database>_owner role owns every object the first deploy re-owns in public, migration, and the workload's schemas (see What the first deploy re-owns). A workload that served before continuous delivery created its objects as its own login. The check names the first objects and their owners. The next continuous-delivery deploy re-owns them, and until then the fix prints one transaction per database that re-owns them by hand.
project-identity No deployment or datasource record is still keyed by a workload's manifest name instead of its workspace path.

These checks can answer unknown:

  • runtime-operation-grants and runtime-binding-grant-config are unknown when the control plane cannot read Runtime's grants: Runtime did not answer, or it refused the read. Runtime answers grant reads only for a signed-in user, so a run with a machine token, such as in CI, reads both checks as unknown. Run the command after putnami cloud login. The detail names the reason.
  • runtime-binding-grant-config is also unknown on a control plane that is not configured with config-api's service account. You cannot fix that from your workspace.
  • database-ownership is unknown for a workload whose database does not exist yet: the first deploy creates it. It is also unknown when you do not hold platform.workspace.manage on the workspace: the platform's data service reads each database with the platform's database authority, so the control plane asks it only for a workspace manager. The fix then says to run the command as a manager. The check is unknown too when the data service cannot answer. The detail names the reason, and the fix prints, for each database, the query that lists every object the deploy would re-own. Before the first continuous-delivery deploy, <database>_owner does not exist yet: the check reads failing, and the fix says that deploy creates the role and re-owns the objects.
  • project-identity is unknown when the control plane does not know the workloads' manifest names. The command sends them from your checkout; it cannot when putnami.ci.json selects no workload for the environment.
  • Every control-plane check is unknown when the command cannot reach the control plane or resolve your session. The detail names the failure.

A migration bundle exists only after a build, so run putnami build first if a workload owns migrations. With --output=json, data is the status node: one child per prerequisite under data.children, with ids such as env.doctor.oci-registry, and the counts under data.metrics. A failed command still carries them.

What the first deploy re-owns in a database

A workload that served before continuous delivery created its database objects as its own login. Its first continuous-delivery deploy re-owns them to <database>_owner, in public, migration, and the workload's schemas:

  • schemas;
  • tables, partitioned tables, foreign tables, views, materialized views, and sequences;
  • functions, procedures, aggregates, and window functions;
  • enum types, composite types, and domains.

It does not re-own these objects:

  • range types and base types;
  • members of an extension, such as pgaudit's functions;
  • routines internal to a type, such as a range type's constructors;
  • a sequence owned by a table column: it moves with its table;
  • an object whose owner the db-provisioner can neither act as nor borrow, such as one owned by Cloud SQL's built-in postgres user or a password user. The deploy skips it and continues. The database-ownership check keeps listing it, and the fix says who can re-own it: a superuser, or the db-provisioner once it is a member of that owner. A table among these objects still fails the deploy's grants;
  • every object in a schema that such an owner owns, whoever owns the object: <database>_owner cannot create in that schema, so the deploy skips those objects too. The check lists them as waiting for their schema. The deploy's grants on that schema still fail until a superuser re-owns it to <database>_owner; the next deploy then adopts the objects.

The deploy grants <database>_app what the owner's default privileges give: SELECT, INSERT, UPDATE, and DELETE on each re-owned table and view, and USAGE and SELECT on each sequence. The migration schema stays read-only for <database>_app.

The previous serving login keeps working. A Cloud SQL IAM service-account login (…@….iam) that owned at least one table in those schemas is granted <database>_app. A login that owned only a view, a sequence, a routine, or a type is not. The grant stays after the old revision is retired. Once no revision serves as that login, revoke it as the db-provisioner:

REVOKE "<database>_app" FROM "<login>";

Re-owning a relation locks it (ACCESS EXCLUSIVE) until the deploy's database bootstrap commits. The bootstrap waits at most 5 seconds for each lock. When the old revision holds a relation longer, the deploy fails instead of making the old revision's queries wait, and the next deploy retries. A later deploy finds nothing to re-own and locks nothing.

Enable the environment in one command

putnami cloud env doctor tells you what is missing. putnami cloud env enable applies every fix your workspace owns, then prints the prerequisites as a table, one row per prerequisite: ok, missing, degraded, or unknown:

putnami cloud env enable prod

It runs the doctor checks first, converges each row that is not ok in the order the table lists them, then reads the checks again:

Row What enable does
put-binding, oci-binding Activates the namespace binding under the distribution.namespace of putnami.ci.json.
environment-definition Accepts putnami.ci.json from the head of your repository's default branch, resolved by the control plane. Pass --source-revision <commit> to accept another commit. It never reads your local checkout. The control plane then deploys each workload the definition newly selects from the release set the channel points at now.
runtime-operation-grants Enables the Runtime operation grant of each caller the control plane names.
runtime-binding-grant-config Enables config-api's Runtime binding grant.
oci-registry, ci-envs, publish-namespaces Reported only: these are edits to files in your checkout. The row prints the fix.
database-ownership, project-identity Reported only: an operator or the first deploy converges them. The row prints the fix.

The command prints one line per step, applied, skipped, failed, or reported, with the fix under each failed or reported step, then the doctor table:

Enable prod of workspace 0b8f3c9e-…

applied   put-binding                   activated put namespace acme (idempotency key acme-put)
applied   environment-definition        accepted revision 1 at source revision 4f2e… (default-branch head)
skipped   runtime-operation-grants      cpa-worker@… already enabled at revision 3
reported  database-ownership            not written by this command: objects in acme_shop are owned outside acme_shop_owner
          fix: BEGIN; ALTER TABLE … OWNER TO acme_shop_owner; COMMIT;

3 applied, 0 failed

Environment prod of workspace 0b8f3c9e-…
…

Running it again on the same commit writes nothing: every write reads the current revision first and sends it as the expected revision, so a concurrent change fails the step with the revision moved instead of overwriting it, and a second run finds nothing to do. The environment definition is checked again on every run: the commit of the latest revision is replayed, and any other commit, even one with the same putnami.ci.json, is accepted as a new revision. A head commit that a later revision replaced is accepted again the same way, so the head becomes the latest definition without a new commit. A failed step does not stop the others. The command exits 1 when any step failed or any row is still missing, and 0 otherwise.

The command needs platform.workspace.manage in the workspace. A session without it is refused in one line before any write. A row the doctor could not check is reported, not written, because a write on a guess could apply the wrong fix. With --output=json, the steps are under data.steps, the counts under data.applied and data.failed, and the doctor result under data.readiness.

What happens when you merge

Your rules already say which channels a trigger publishes. With the rule below, a merge to main publishes every impacted project and advances canary:

{
  "rules": [
    { "branches": "main", "publish": ["canary"] }
  ]
}

The chain from there is:

  1. The run publishes the impacted projects and releases one immutable release set.
  2. Accepting that release advances canary to the new set, and the platform emits one release_set.channel.advanced fact.
  3. The control plane consumes the fact, finds every environment that follows canary, and compares the set to what each environment runs right now.
  4. It deploys only the workloads whose image, config, migrations or deployment declaration differ.

No step in that chain is a call from the CI run to the control plane. The run reports its own lifecycle and nothing else; the accepted channel move is what triggers the deployment. The fact records cause: release for this path.

Only the commit main points at when the release happens may advance a channel. When two merges land close together, the run for the older commit fails its release instead of moving canary back to older code, and its run turns red. The run for the newer commit publishes and deploys. Pull-request channels and tag channels are not affected.

Add a workload that was never deployed

A workload an environment follows needs no first deploy by hand. In its putnami.json, set options["@putnami/cloud"].deploy.enabled to true and turn on its deployment declaration: options["@putnami/go"].deployment: true or options["@putnami/typescript"].deployment: true. Then select it in the environment's workloads.

When the control plane accepts the definition that selects it, it deploys the workload from the release set the environment's channel points at now. You do not wait for the next move, and a merge that publishes nothing new still deploys it once putnami cloud env enable <env> accepts the definition. When that release set has no image or config for the workload, the next move that carries them deploys it. Before its first revision, the platform creates the workload's runtime service account and a closed placeholder service in your workspace's cloud project, then deploys the workload over it. A workload without a deployment declaration and without an earlier release is not deployable: the move fails it. Turn its deployment declaration on.

The platform remembers a workload it deployed once, even after its Cloud Run service is deleted. The next move creates the placeholder service again under the same names and the same runtime service account, then deploys the workload over it. You do nothing.

The platform does this only when it still owns the runtime service account the workload ran as. When that account was deleted or replaced, or when the workload's registration names another service or account, the move fails the workload with a message that names the operator runbook docs/runbooks/retired-service.md. Ask an operator to delete the workload's service and registration, and the next move deploys it as a new workload.

Promote an existing set

A promotion points a second channel at a release set that already exists — the usual canary to stable step. It is the same immutable set, so no artifact is rebuilt.

The channel set is a Distribution provider operation. The platform serves it through the release-set provider seam, which takes a protocol request file:

putnami cloud release-set channel-set --request-file /absolute/path/request.json

The file must be an absolute path to a regular, mode-0600 file.

Every environment that follows the target channel then synchronizes exactly as it does on a merge. The only difference an environment sees is the fact's cause: advance.

Rolling back is a promotion too: point the channel at the previous set. That is a new move with its own generation, so it opens its own deployment run.

Read the result

A run a channel move opened is marked on the deploy reads — the release status, the deploy history, the watch stream, and the per-project deployment view. Each project carries provenance: channel-move instead of cli, and the run carries a trigger object:

{
  "trigger": {
    "kind": "channel-move",
    "namespace": "acme",
    "channel": "canary",
    "generation": 42,
    "cause": "release",
    "moved_at": "2026-09-14T09:12:04Z",
    "release_set_id": "rs_9f2c…",
    "source_revision": "4eb9cac6d…",
    "fact_revision": 137
  }
}
Field Answers
channel, namespace which channel moved
generation that channel's own counter for this move; it increases by one per accepted move
cause release for a publish, advance for a promotion
moved_at when the channel moved, not when the deployment started
release_set_id the immutable set the environment was moved onto
source_revision the commit the deployed content was cut from

Show one release, with the state of each workload, with:

putnami cloud deploy status <release-id>

It prints a status node, with one check per workload. It exits 1 when the release failed, or ended partial or skipped. A release still converging reads degraded and exits 0. Its structured output carries no trigger: run putnami cloud env status --provenance --output=json to read the trigger of each project's last run.

There is no filter for triggered runs. The trigger object is present on the runs a move opened and absent on the ones you submitted, so filter on it in your own tooling.

When a move deploys nothing

Not every channel move produces a deployment. Each case below is recorded on the move rather than dropped:

Outcome What happened
no_follower No environment of the accepted definition follows that channel, or the control plane has accepted no definition for the workspace.
not_deployable The release set does not cover a workload an environment declares. The record names the workload — for example a project that published no image member, or no config member, in that set. One uncoverable environment holds the whole move: no follower of that channel is deployed.
converged Every declared workload already runs exactly these artifacts. Nothing differs, so nothing is deployed.
superseded A later generation of the same channel already settled, whether or not it deployed anything. The older move is dropped instead of walking the environment backwards onto a stale set.

A move that arrives twice is a replayed delivery: the second delivery is a no-op, and the move keeps the outcome it already recorded. One move opens at most one run per environment.

A move also deploys a subset of an environment. The comparison is per workload, over three things: the container image, the authored config document, and the ordered list of migration bundles. A workload whose three match is left running; a workload whose last deployment failed or is still in flight is redeployed, because its state is unknown.

Not yet supported

Not supported What happens instead
constraints.approval: manual The environment is not deployed by a channel move.
Progressive rollouts (rollout.strategy: progressive, steps, timed advance, abort signals) Only all-at-once is accepted.
Environment variants An environment declaring variants is refused.
An environment whose workloads follow different channels The move is recorded as not deployable rather than deploying part of the environment.

Next