Hosted CI

Connect a repository and enable its workspace subscription to run the declared putnami.ci.json pipeline on pushes and pull requests.

Hosted CI owns verification and publication. Continuous deployment starts after an accepted publication moves a channel; the environment follows that channel independently.

Connect and enable

Link the GitHub repository, then enable CI for the current Cloud workspace:

putnami cloud source connect --repo <owner>/<repo>
putnami cloud ci enable
putnami cloud ci subscription --output=json

New subscriptions use the canary runner channel. To hold the runner on the stable channel explicitly, run putnami cloud ci enable --runner-channel stable. ci disable revokes admission without deploying or deleting a service.

Declare the pipeline

The root putnami.ci.json names the commands, common flags, runner selection, publication channels, and trigger rules. A minimal main-and-pull-request shape is:

{
  "$schema": "https://putnami.dev/schemas/putnami-ci.json",
  "version": 3,
  "commands": ["lint", "test", "build", "validate"],
  "runner": { "selection": "impacted", "timeoutMinutes": 45 },
  "rules": [
    { "pullRequests": true, "publish": ["pr-{number}"] },
    { "branches": "main", "publish": ["canary"] }
  ]
}

Publication creates immutable release-set members and advances only the channels selected by the matching rule. Add envs when an environment should deploy itself after one of those channels advances.

Read a run

putnami cloud ci list
putnami cloud ci view <run>
putnami cloud ci logs <run> --level error
putnami cloud ci logs <run> --follow
putnami cloud ci status

Run IDs accept an unambiguous prefix. view summarizes phases and failed tasks; logs carries the detailed stream. For performance and cost evidence, use ci usage, ci insights <run>, and ci timings <run>.

Recover deliberately

Mutating recovery commands require an audit reason. In a non-interactive environment, also pass --yes to bypass the confirmation prompt.

putnami cloud ci retry <run> --phase lint --reason "transient failure"
putnami cloud ci retry <run> --phase deploy --reason "registry 503 during the rollout"
putnami cloud ci cancel <run> --reason "superseded commit"
putnami cloud ci repair --reason "reconcile stale run state"

ci pause, ci drain, and ci resume change the workspace pipeline mode and also require --reason. Use them as circuit-breaker operations, not as normal run controls.

Retry a failed deployment

ci retry <run> --phase deploy reopens the rollout of a run whose deploy phase concluded failure. It opens no new run: the control plane deploys the same release set to the same environment again, under a new release id, and the run's deploy phase gets a new attempt that carries that rollout's verdict. ci view <run> lists every attempt; --reason is recorded with the attempt.

The retry is refused when there is nothing to reopen:

Answer Why
400 the run declared no control-plane deploy, or its deploy never started
409 the deploy is still rolling, concluded something other than failure, opened no release, already succeeded, or the channel moved on since (the next move covers the environment)
503 this Delivery is not wired to the control plane's release retry

A second retry while the reopened rollout runs is refused with the attempt that is still rolling; it opens nothing.

Select producer tracks

A workspace can follow a producer channel or pin one exact immutable release set. The update is atomic and preserves the workspace's other tracks:

putnami cloud track --namespace putnami --channel stable
putnami cloud track --namespace putnami --channel canary
putnami cloud track --namespace putnami --release-set <release-set-id>

Add --runner-channel stable|canary to change the runner channel in the same update. The CI subscription must already exist.

Complete command matrix

These are all 17 cloud ci verbs. Authentication and routing flags shared by every verb are --workspace, --auth-url, --client-id, and --control-plane-url; they are omitted from the rows below.

Command Purpose Command-specific flags and arguments
ci enable Create or enable the workspace CI subscription optional --runner-channel stable|canary
ci disable Revoke new-run admission no command-specific flags
ci subscription Read the current subscription revision and settings optional --output=json
ci list List runs newest first and filter the fetched window --limit, --repo, --sha/--ref, --branch, --pr, --status, --phase, --age
ci view <run> Read one run, its attempts, and failure diagnostics an unambiguous run-id prefix
ci start Start a run for a pushed commit required --repo, --sha, --reason; optional --ref, --branch, --pr, --phases, --provider, --size, --max-parallel, --no-cache, --yes
ci cancel <run> Cancel one run idempotently required --reason; optional --yes
ci retry <run> Retry the whole run or one phase; --phase deploy reopens a failed rollout on the same run required --reason; optional --phase, --size, --max-parallel, --no-cache, --yes
ci logs <run> Read or follow the detailed log stream --raw, --follow, --phase, --project, --q, --level, --from, --to, --cursor, --limit
ci status Read aggregated CI readiness dimensions no command-specific flags
ci usage Aggregate substrate, profile, gate wall, and estimated spend optional --window (default 168h)
ci insights <run> Read the contracted gate and cache-economics report optional --output=json
ci timings <run> Read the per-task timeline, longest wall first optional --limit, --output=json
ci repair Terminalize stale rows and reconcile terminal checks required --reason; optional --yes
ci pause Stop new admission with an audited circuit-breaker change required --reason; optional --cancel-running, --review-ref, --incident-ref, --yes
ci drain Stop new admission while allowing running work to drain by default required --reason; optional --cancel-running, --review-ref, --incident-ref, --yes
ci resume Return the workspace pipeline to active mode required --reason; optional --cancel-running, --review-ref, --incident-ref, --yes

ci help --output=json returns the installed command inventory for automation. The manifest currently declares 33 CI flags; every one is either named in this matrix or in the shared-flags sentence above.

Next