> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks and approvals

> Find, review, approve, cancel, retry, and debug the tasks behind deployments and infrastructure changes from the Ryvn CLI

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](https://ryvn.ai/docs/cli.md). For the approval policy itself, see [Deployment approvals](https://ryvn.ai/docs/guides/deployment-approvals.md).

## Which commands create tasks

Not every command starts a task, and the ones that do differ in whether they wait for it.

| Command | Starts a task | Waits for it |
| - | - | - |
| `ryvn command rollback`, `enforce-deploy`, `trigger-job`, `dry-run`, `restart` | Yes | Yes, until the task ends |
| `ryvn command redeploy installation` | Yes | Yes |
| `ryvn command pin`, `unpin` | No | Returns immediately |
| `ryvn command sync-artifacts` | Artifact copy tasks | No. Prints the copy tasks it started or found, then exits |
| `ryvn create -f environment.yaml`, `ryvn update environment` | A plan for the infrastructure change | No. Prints the plan's task ID |
| `ryvn create`, `replace`, `update`, `delete` on other resources | Possibly, as a result of the change | No. Returns when the API accepts the change |

`pin` and `unpin` hold or release a release version without deploying. See [Holding a release](https://ryvn.ai/docs/cli.md#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:

```bash theme={null}
ryvn get installation-task my-app -e production
ryvn get installation-task -e production --limit 10
ryvn get installation-task -e production -o json
```

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:

| Suffix | Meaning |
| - | - |
| `[APPROVABLE]` | The task is waiting for approval. |
| `[PREVIEW]` | A plan or dry run that completed and applied nothing. |
| `[APPROVED]` | A plan that was approved. The change runs as a separate task, so check that task for the result. |

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:

```bash theme={null}
ryvn describe environment production
```

```
Infrastructure:
  Latest:     <description> (<status>)
  Task ID:    550e8400-e29b-41d4-a716-446655440000
  Approve:    ryvn task approve 550e8400-e29b-41d4-a716-446655440000
```

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.

```bash theme={null}
ryvn describe installation-task <task-id>      # status, attribution, timing, failure reason, logs
ryvn describe installation-task <task-id> -v   # adds per-resource changes
ryvn task get <task-id>                        # rollout progress and resources waiting to become ready
ryvn task output <task-id>                     # the plan or diff the task produced
```

* `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](https://ryvn.ai/docs/guides/deployment-approvals.md) 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**

```bash theme={null}
ryvn task output <task-id>
```

**3. Approve, cancel, or retry**

```bash theme={null}
ryvn task approve <task-id> --reason "plan reviewed, adds one node pool"
ryvn task cancel  <task-id> --reason "wrong version"
ryvn task retry   <task-id> --reason "transient registry error"
```

> [!WARNING]
>
> 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.

| Flag | Default | Effect |
| - | - | - |
| `--no-watch` | off | Create the task and print `ryvn get installation-task <name> -e <env>` instead of watching. The task ID is not printed. |
| `--timeout` | `10m` | How long the CLI watches. The task keeps running if the timeout expires. |
| `--poll-interval` | `5s` | How often the CLI checks status. The minimum is `2s`. |
| `--reason` | auto-filled | Annotation stored with the action. |
| `-o json` | | Prints the final task as JSON instead of progress lines. |

`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

| You want to | Use |
| - | - |
| Run the deployment again with the same config, for example to pick up variable group or secret changes | `ryvn command redeploy installation my-app -e production` |
| Change config, env vars, secrets, or the release channel | `ryvn update installation my-app -e production -p '...'`, then follow the resulting task |
| Re-run a task that failed, with no changes | `ryvn task retry <task-id>` |
| Restart pods without a version or config change | `ryvn command restart -e production -i my-app` |
| Go back to the previous deployment | `ryvn command rollback -e production -i my-app` |
| See what a deployment would change, without applying it | `ryvn command dry-run -e production -i my-app` |

`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.

```bash theme={null}
ryvn delete installation my-app -e production
ryvn delete installation api worker -e production
```

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:

```bash theme={null}
ryvn get deletion <deletion-id>
ryvn delete deletion <deletion-id> --reason "wrong installation"
```

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:

```bash theme={null}
ryvn delete environment staging
```

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.`

> [!WARNING]
>
> `--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**

```bash theme={null}
ryvn describe installation my-app -e production
```

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

**2. Read the failing task**

```bash theme={null}
ryvn get installation-task my-app -e production --limit 5
ryvn describe installation-task <task-id>
```

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**

```bash theme={null}
ryvn task output <task-id>
```

**4. Check the Kubernetes objects**

```bash theme={null}
ryvn get manifest my-app -e production
ryvn describe manifest pods -i my-app -e production
ryvn describe manifest deployment/my-app -i my-app -e production
```

`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**

```bash theme={null}
ryvn logs installations my-app -e production --level error --since 1h
```

See [Logs](https://ryvn.ai/docs/observability/logs.md#view-logs-from-the-cli) for filters and limits.

**6. Run kubectl against the cluster**

```bash theme={null}
ryvn connect production -- kubectl get pods -A
```

This needs a permission set and may wait for approval. See [Just-in-time kubectl access](https://ryvn.ai/docs/guides/jit-kubectl-access.md).

For a service that is running but misbehaving, `ryvn metrics network my-app -e production` shows requests, errors, and latency. See [Network metrics](https://ryvn.ai/docs/cli.md#network-metrics).

### Common causes

| Symptom | What to check |
| - | - |
| A task never starts or never finishes | It may be waiting for approval. `ryvn get installation-task` shows `[APPROVABLE]`, and `ryvn task output <id>` shows the plan. |
| A deployment fails because a version is missing | Check that the release exists: `ryvn get release -s my-service`, or `ryvn describe service my-service`. |
| The installation does not pick up an update | Run `ryvn describe installation`, then check for a pending task. A pinned installation ignores release-channel updates until you run `ryvn command unpin`. See [Holding a release](https://ryvn.ai/docs/cli.md#holding-a-release). |
| Pods restart repeatedly | Read the events with `ryvn describe manifest pod -i my-app -e production`, then the logs. |

## Provision and approve an environment

Creating an environment, or changing its config or platform inputs, plans the infrastructure change:

```bash theme={null}
ryvn create -f environment.yaml
ryvn update environment staging -p '{"spec": {"config": {"region": "us-east-1"}}}'
```

`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:

```bash theme={null}
ryvn task output <task-id>
ryvn task approve <task-id>
```

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:

```bash theme={null}
ryvn logs environments staging --follow
```

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:

```bash theme={null}
ryvn provision environment staging
ryvn deprovision environment staging
```

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`.

> [!NOTE]
>
> 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.
