Your first deploy
You will make a project deployable, point an environment at a channel, merge, and confirm the project is running — using only real commands and config.
By the end you will have added one file (infra/runtime.json), declared one
environment in putnami.ci.json, and released a revision attributable to your
commit.
Before you start
Complete the earlier steps once:
- Install the cloud extension —
putnami deps add @putnami/cloud - Log in —
putnami cloud login - Set up the workspace —
putnami cloud setup - Check the workspace contracts — know which file owns each change
- Connect the repository —
putnami cloud source connect --repo <owner>/<repo>
You also need a project that builds:
putnami build1) Declare how the project runs
Add infra/runtime.json to the project. Its presence is what makes the project
deployable. A minimal scale-to-zero service:
{
"ingress": { "domains": ["hello.example.com"] },
"scaling": { "max": 2, "concurrency": 500 }
}ingress.domains— the hostname(s) the service answers on. For an internal-only service, use{ "public": false }instead.scaling.maxandscaling.concurrency— workload-owned capacity ceilings. Infra protocol v2 does not expose a workload-levelminoverride. The CPA owns the variable-cost posture: the service always scales to zero and cold-starts on the next request.
See Deploy & hosting for every field.
2) Turn on the continuous deploy
There is no deploy command to run. Your project deploys through an environment
that follows a channel: a merge to main publishes the project, the publish
moves the channel, and the environment deploys itself.
In the project's putnami.json, turn on its deploy and its deployment
declaration (use @putnami/typescript for a TypeScript project):
{
"options": {
"@putnami/cloud": { "deploy": { "enabled": true } },
"@putnami/go": { "deployment": true }
}
}In putnami.ci.json, publish main to a channel and declare an environment
that follows it:
{
"rules": [
{ "branches": "main", "publish": ["canary"] }
],
"envs": {
"prod": {
"channel": "canary",
"workloads": [{ "select": ["apps/hello"] }]
}
}
}Environments follow channels explains every field.
3) Check and enable the environment
putnami cloud env doctor prod
putnami cloud env enable prodenv doctor checks each prerequisite and prints the fix for every one that is
missing. It changes nothing. env enable applies every fix your workspace owns,
then prints the same checks again. A second run on the same commit writes
nothing.
4) Merge
Open a pull request with these changes and merge it. The run on main builds
and publishes the project, then moves canary. The platform deploys every
environment that follows canary.
The release is zero-downtime: the previous revision keeps serving until the new one is Ready.
5) Confirm it
putnami cloud env status prod --health
putnami cloud deploy status <release-id>
putnami cloud config # the config the running revision resolvesenv status shows the serving revision, the most recent run, recent errors,
and whether the served commit is on your local main. It never fetches, so
update your local Git refs before relying on the ON MAIN result.
env status prod --provenance prints the release id of each project's last
run. deploy status shows one release and the state of each project, with the
failing stage and reason when it failed.
Redeploy and roll back
- Redeploy by merging again. Only the projects whose image, config, migrations or deployment declaration changed roll.
- Roll back an environment by pointing its channel at an earlier release
set:
putnami cloud channels set canary --from <rs_id>. The environment deploys that set like any other move.
Next
- Environments follow channels
- Managed runtime — scaling, config & bindings
- Database — datasources and migrations
- Observability — logs, metrics, traces
- Hosted CI — verify and publish on repository events