Workspace contracts

Each workspace file owns one part of the delivery contract. Keeping runtime, resources, configuration, and automation separate makes a change reviewable before it reaches Cloud.

Use this page when you need to decide where a new setting belongs or which validation proves it.

Find the owning file

File Owns
putnami.workspace.json Workspace-wide extensions, registries, and the committed Cloud workspace link
<project>/putnami.json Project identity, dependencies, capabilities, and publishable artifact kinds
<project>/infra/runtime.json Whether a workload is deployable, plus ingress, scaling, resources, and runtime security
<project>/infra/requirements.json Named databases, storage, events, and secret requirements that Cloud resolves into bindings
<project>/schema/config.json The shape, types, and visibility of application configuration
<project>/conf/env.<env>.yaml Non-secret authored values for one environment
putnami.ci.json Hosted CI commands, runner policy, publication channels, trigger rules, and followed environments

Secrets never belong in conf/env.<env>.yaml or a committed manifest. Declare the requirement, then write the value through putnami cloud secrets.

Make a service deployable

The presence of infra/runtime.json makes a project deployable. This minimal declaration exposes one domain and allows the service to scale to zero:

{
  "ingress": { "domains": ["hello.example.com"] },
  "scaling": { "max": 2, "concurrency": 500 }
}

Add infra/requirements.json only when the service consumes a managed resource. The logical names in that file are application-facing identities; provider resource names and credentials stay under platform ownership.

{
  "$schema": "https://putnami.dev/schemas/putnami-infra.json",
  "protocolVersion": 2,
  "storage": [
    { "name": "uploads", "access": "readwrite" }
  ]
}

Validate before publishing

Run the broad project contract first, then the Config-specific check when the project publishes native Config:

putnami validate --projects <project>
putnami cloud validate-config <project> --env prod
putnami deploy --preview

cloud validate-config is local and read-only. It reads the existing schema, authored fields, values, workspace link, version, and repository revision; it does not build, create a package, or contact Cloud. Generate required build artifacts before calling it so you do not validate a stale schema.

deploy --preview asks the control plane for the deployment decision but does not publish or provision anything.

Do not edit generated contracts

Files below .gen/ are build outputs or immutable publication inputs. In particular, do not hand-edit .gen/version.json, .gen/migration-bundle/, .gen/schema/http-routes.json, or .gen/requirements.json. Change their authored source and regenerate them with the project build instead.

Next