# Review a deployment

Approve or reject a job that waits at an environment with reviewers.

Replace repo-id with the repository's id and approval-id with the approval's id.

## Prerequisites

- `ci:ReviewDeployments` on the repository (`rn:ews::<organization id>:ci:repository/<repository id>`),
  **and** a place on the environment's reviewer list. With the environment's `preventSelfReview`,
  the person who started the run cannot approve it.
- `ci:ListEnvironments` on the repository to see the waiting jobs, in the console and in the API.
- In the console, also `git:GetRepository` and `ci:GetRun` on the repository to open the run;
  without them the run page is not found.

## Find the waiting jobs

**Console**
1. Open the repository, then open its **CI** tab.
2. Open the run.

Under **Deployment reviews** the page lists each job of the run held at an environment, with the
reviewers it waits for, or the decision and who made it.

**CLI**
```sh
dcloud ci environments approvals repo-id
```

**API**
```http
GET /ci/api/repositories/repo-id/approvals
```

The list holds up to 100 approvals, newest first, only those still `waiting` unless you ask with
`all=true`. Each says `youMayReview`: whether you are on its reviewer list and not barred as the
person who started the run.

## Decide

**Console**
1. (Optional) Enter a comment in the box under the list. It is recorded with the decision.
2. Choose **Approve and deploy**, or **Reject**.

The buttons appear only on a waiting job you may review and only with `ci:ReviewDeployments`.

**CLI**
```sh
dcloud ci environments review approval-id --decision approve --comment "Release 1.4"
```

**API**
```http
POST /ci/api/approvals/approval-id/review
{ "decision": "approve", "comment": "Release 1.4" }
```

## Result

The answer is `200` with the approval's new status, `approved` or `rejected`. An approved job goes
on once the environment's wait timer, which started when the job arrived, has run out. A rejected
job fails. The waiting step of a job on the hosted machines picks the decision up within ten
seconds. Approvals and rejections are recorded in the audit log.

- `403` "Forbidden: you are not a required reviewer of this environment".
- `403` "Forbidden: this environment does not let the person who started the run approve it".
- `409` "Already approved" (or `rejected`, `expired`) when the approval was decided before.

A job that nobody reviews within 5 h 30 min expires and fails. On the one-machine-per-run hosted
machines the run's two-hour limit ends the wait first.

## Related

- [Protect a deployment with an environment](protect-a-deployment.md)
- `ci.environments.review` · `dcloud ci environments review`
