# swb approve-deploy

Lets a deploy waiting at its gate through.

## Synopsis

```
usage: swb approve-deploy <deploy-id> --env <env> [--reason <text>] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<deploy-id>` | One **deploy id**, as [`swb deploys --status AWAITING_GATE`](/command-line/deploys) prints it: a deploy waiting for an approver. Required. | — |
| `--env` | An environment's **name or id**; a name is matched first. The deploy must be of this environment. Required. | — |
| `--reason` | Text: why you let it through, kept on the deploy beside your name. | none |
| `--json` | Nothing. Prints the deploy as the API answered it instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it does

An environment whose subscription carries a gate holds each deploy for a
second person before anything it deploys changes. The deploy plans what it
will do — for an app, its change set, which `swb deploys` and the install's
page show — and waits, `AWAITING_GATE`, for up to thirty days.

`swb approve-deploy` calls `Mutation.approveDeploy`: the deploy records your
approval, when you gave it and your reason, and goes on to deploy what it
planned, ending as any deploy ends. The person who asked for a deploy never
approves it: whoever ran it, held the version it deploys or released that
hold. A deploy dispatch wrote for a release's move is dispatch's request, so
the person who approved the release may approve it.

A second approval of the same deploy is refused rather than applied twice, so
the command takes no client token.

## What it prints

```
ID                                                    APP          VERSION  STATUS         APPROVED                                          REJECTED
switchboard#production0925#2026-10-20T10:00:00.000Z#d1  switchboard  9.10.0   AWAITING_GATE  ana@lime-energy.com · 2026-10-20 11:00: checked on dev  —
```

— the deploy as the control plane answered it: its id, its app and version,
its status — still `AWAITING_GATE` for the moment its execution takes to move
it on — and who approved or rejected it, when and why.

`--json` prints the deploy as the API answered it.

## The operation and the permission

`Mutation.approveDeploy`. The caller needs `swb.deploys.approve` on the
tenant, which the `release-approver` role carries. `swb approve-deploy` also
reads `Query.me` once for the tenant and `Query.tenant` to turn the `--env`
name into an id.

## Refusals and exit status

Exit status is 0 once the deploy is approved, and 1 on every refusal below.

| Refusal | When |
|---|---|
| `swb approve-deploy takes <deploy-id>` | No deploy was named. |
| `swb approve-deploy needs --env <env>` | `--env` was not given. |
| `no environment named "<env>" in tenant <tenant> (have: dev, staging, prod)` | No environment of the tenant has that name or id. |
| `not signed in or token expired — run swb login` | There is no usable credential. |
| `NotFound: Deploy <id> not found` | The tenant has no such deploy. |
| `ValidationFailed: …` | A deploy of another environment, or an id that is no deploy's. |
| `Conflict: deploy <id> is <STATUS>: …` | The deploy is not waiting at its gate. |
| `Conflict: deploy <id> is not yet ready to approve: …` | It is still being planned; its execution has not parked on it yet. |
| `Conflict: deploy <id> is already approved, …` | Someone approved or rejected it first. |
| `Refused: deploy <id> was asked for by you, …` | You asked for the deploy. |
| `TaskTimedOut: …`, `TaskDoesNotExist: …` | Step Functions refused the waiting deploy's token, in its own words: its thirty days ran out, or a newer version replaced it. Nothing was recorded. |
| `NotAuthorized: …` | The caller lacks `swb.deploys.approve`. |

## Example

```console
$ swb deploys --env production --status AWAITING_GATE
$ swb approve-deploy switchboard#production0925#2026-10-20T10:00:00.000Z#d1 --env production --reason "checked on dev"
```