Skip to main content
Every change that touches running infrastructure, such as a deployment, a rollback, a Terraform plan, or a teardown, runs as a task. A task has a status, a log, and sometimes a plan that waits for approval. This page covers how to find tasks, review plans, approve or stop them, and work out why one failed. For CLI setup and the main verbs, see CLI. For the approval policy itself, see Deployment approvals.

Which commands create tasks

Not every command starts a task, and the ones that do differ in whether they wait for it. pin and unpin hold or release a release version without deploying. See Holding a release. create, replace, update, and delete do not accept --reason, --no-watch, --timeout, or --poll-interval. To follow what they started, look up the task as described in the next section.

Find a task

List the latest tasks for one installation, or for every installation in an environment:
With a name, the command lists that installation’s tasks. Without one, it lists tasks across the whole environment and adds an INSTALLATION column. --limit caps the number of tasks returned. -e is required. The aliases installation-tasks and task also work. The table has the columns STATUS, TASK TYPE, ROLLOUT, ENV CONFIG, AGE, DESCRIPTION, and TASK ID. A status carries a suffix when it matters: If you pass a task UUID instead of an installation name, the command shows that task, like ryvn task get. An environment’s infrastructure tasks, such as provisioning plans, appear under Infrastructure in the environment description:
The Approve: and Retry: lines appear only while the task can be approved or retried. ryvn get environment also shows Plan Awaiting Approval, Planning, or Plan Failed in its status column when a plan decides what happens next.

Inspect a task

Three commands show different parts of a task.
  • describe installation-task is the first stop for a failed task. It prints the failure reason and the task log.
  • task get shows deployment settings, workload counts, resources still waiting to become ready, and pod details when available. The states reflect the task’s last update, not the installation’s current health.
  • task output prints the Terraform plan, Pulumi preview, Helm diff, or artifact sync report for a task, including the result of a dry-run. If a task has no output, the command says No resource changes in task output.
All three accept -o json.

Review a plan, then approve

When an environment or service requires approval, a task stops after it produces a plan or diff and waits. The plan can be a Terraform plan, a Pulumi preview, or a Helm diff. Deployment approvals explains what decides whether a task waits.
1

Find the task

Use ryvn get installation-task my-app -e production, or the Task ID under Infrastructure in ryvn describe environment. A command that watches also prints the ID in its first line, unless you passed --no-watch.
2

Read the plan

3

Approve, cancel, or retry

Approving a plan authorizes the change it describes. Read ryvn task output first, and take extra care with plans that destroy or replace resources. Write a --reason that says what actually happened, because the reason is stored in the audit trail.
  • cancel stops a task that is running or pending. A finished plan that is waiting for approval can’t be cancelled. To keep it from applying, don’t approve it.
  • retry re-runs a task that failed. If the cause was a bad config or version, fix that first, because a retry repeats the same task.
  • Each of the three also accepts -o json, which prints {"taskId": "...", "status": "accepted"}. The commands print Approval requested, Task cancelled, or Task retried. Approval is asynchronous, so these confirm the request, not the result. Check the task afterwards.
  • A Pulumi approval authorizes the previewed operation, not identical changes. Pulumi recalculates the changes when execution starts.

The --reason flag

--reason is optional. On task approve, cancel, and retry it stays empty when you omit it. It also works on ryvn command operations, except sync-artifacts, which rejects it. When you omit it there, the CLI fills it in with cli preview (commit sha: <sha>), or cli preview (uuid: <id>) when it cannot read a commit SHA. redeploy uses cli redeploy in place of cli preview. task approve, cancel, and retry take only a task ID. The CLI finds the installation by searching your environments’ recent activity. If the task does not appear there, the command fails with task <id> not found in any environment's recent activity.

Watch a command

Task-creating ryvn command operations poll until the task ends. They print Watching task <id> for installation '<name>'..., each status change, the task log, and a final summary. Statuses that end the watch are COMPLETED, FAILED, and CANCELLED. A failed or cancelled task makes the command exit with an error. When the task is approvable or retryable, the summary prints the ryvn task approve or ryvn task retry command to use next. ryvn command dry-run runs a Helm diff or Terraform plan without applying it. Add --disable-approvals to create a preview that cannot be applied. If a watch ends with timeout after <duration>, the task is still running. Check the existing task with ryvn get installation-task or ryvn task get <task-id>. Don’t rerun the original command to keep watching: that submits the operation again, which can run a job twice. Choose a longer --timeout before you start the operation. If the CLI cannot find the task it just created, it fails with no task found in recent activity after 3 attempts. For redeploy, this can mean deployment constraints blocked the task, such as an unmet dependency or an installation that is waiting for a platform blueprint upgrade. Check ryvn get installation <name> -e <env>.

Choose between redeploy, update, and retry

redeploy deploys the installation’s current config and the latest release from its release channel. It changes no configuration.

Delete installations and environments

Deletion starts teardown immediately. Neither command asks for confirmation.
The command prints Installation "my-app" delete request accepted and the commands to check progress. Teardown runs as a task, and where approval is required that task waits like any other. When you delete several installations at once, the command exits with an error if any of them failed, and -o json reports each result. Besides names, delete installation accepts --id (repeatable) and -f with a ServiceInstallation file. A deletion request stays open until its destroy task starts. While one is open, ryvn describe installation my-app -e production shows Deletion: open (<deletion-id>). To inspect or cancel it:
Cancelling keeps the installation. Once the destroy task is running, the deletion can no longer be cancelled. An installation removed from Git is also kept when you cancel its deletion, and Git sync stops managing it until its file is added back. To delete an environment:
This deprovisions the cloud infrastructure first, then removes the environment. It fails with cannot deprovision environment "staging" when Terraform installations remain or deletion protection is on, so delete the installations first. On success you see either Environment "staging" deleted (the environment was never provisioned) or Environment "staging" is being deprovisioned. It will be deleted once deprovisioning completes.
--force on delete installation or delete environment skips the teardown and removes the record at once. Cloud resources such as clusters, load balancers, disks, and DNS records are orphaned. They keep running and keep costing money until you find and delete each one by hand. --force asks for a confirmation code shown in a native dialog, so it works only from an interactive terminal on macOS. It cannot run in CI, over SSH, or from an agent. Use it only when normal deletion is impossible.

Debug a failed deployment

Work from the cheapest, most specific evidence to the most expensive. Stop when you find the cause.
1

Read the installation's state

Look at Deploy, Health, and any open Deletion. Add -o json for the full record.
2

Read the failing task

The failure reason is usually here, for example a version that does not exist or a config error. A task marked [APPROVABLE] has not failed. It is waiting for ryvn task approve.
3

Look at what the task planned

4

Check the Kubernetes objects

describe manifest works like kubectl describe. It shows metadata, owner references, status, spec, and events. Name a resource as TYPE, TYPE NAME_PREFIX, or TYPE/NAME. All three commands accept -o json.
5

Read the logs

See Logs for filters and limits.
6

Run kubectl against the cluster

This needs a permission set and may wait for approval. See Just-in-time kubectl access.
For a service that is running but misbehaving, ryvn metrics network my-app -e production shows requests, errors, and latency. See Network metrics.

Common causes

Provision and approve an environment

Creating an environment, or changing its config or platform inputs, plans the infrastructure change:
ryvn update environment requires a patch. Running it with none is an error. If the CLI prints Created a plan for environment "staging"; provisioning starts once it is approved, review and approve the plan it names:
If it prints Provisioning started for environment "staging", the environment is already applying and needs no approval. Installations cannot deploy until provisioning completes. Follow it with:
An environment provisioned by an external executor applies the change on the executor’s next run instead of planning it for approval.

Run provisioning from your own infrastructure

For an environment provisioned by an external executor, two one-shot commands run a single pending task and exit:
Each polls once for a pending Terraform apply (provision) or destroy (deprovision) task for that environment, claims it, runs it, and exits. When no task is pending, it logs No pending provision tasks found or No pending deprovision tasks found and exits without error. A task already claimed by another worker fails with task <id> already claimed by another worker. The commands authenticate with the credentials in ~/.ryvn/credentials.yaml, or with a service user’s --client-id and --client-secret.
These commands apply or destroy real infrastructure, and deprovision tears down the environment’s cloud resources. Run them only when you operate the executor for that environment.