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:

  1. Install the cloud extension — putnami deps add @putnami/cloud
  2. Log in — putnami cloud login
  3. Set up the workspace — putnami cloud setup
  4. Check the workspace contracts — know which file owns each change
  5. Connect the repository — putnami cloud source connect --repo <owner>/<repo>

You also need a project that builds:

putnami build

1) 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.max and scaling.concurrency — workload-owned capacity ceilings. Infra protocol v2 does not expose a workload-level min override. 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 prod

env 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 resolves

env 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