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 prodIt 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:
failingmeans the prerequisite is missing. The check prints the exact fix.degradedmeans the prerequisite exists but is stale. The check prints the exact fix.unknownmeans 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-grantsandruntime-binding-grant-configareunknownwhen 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 asunknown. Run the command afterputnami cloud login. The detail names the reason.runtime-binding-grant-configis alsounknownon a control plane that is not configured with config-api's service account. You cannot fix that from your workspace.database-ownershipisunknownfor a workload whose database does not exist yet: the first deploy creates it. It is alsounknownwhen you do not holdplatform.workspace.manageon 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 isunknowntoo 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>_ownerdoes not exist yet: the check readsfailing, and the fix says that deploy creates the role and re-owns the objects.project-identityisunknownwhen the control plane does not know the workloads' manifest names. The command sends them from your checkout; it cannot whenputnami.ci.jsonselects no workload for the environment.- Every control-plane check is
unknownwhen 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
postgresuser or a password user. The deploy skips it and continues. Thedatabase-ownershipcheck 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>_ownercannot 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 prodIt 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:
- The run publishes the impacted projects and releases one immutable release set.
- Accepting that release advances
canaryto the new set, and the platform emits onerelease_set.channel.advancedfact. - The control plane consumes the fact, finds every environment that follows
canary, and compares the set to what each environment runs right now. - 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.jsonThe 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. |