# Protect a deployment with an environment

Decide which branches may deploy to an environment, who must approve each deployment, and how long it waits.

An environment belongs to a repository and applies to workflows under `.github/workflows/`. A job
that says `environment: production` (or `environment: ${{ inputs.environment }}`) deploys to it: the
environment's rules decide whether the job may run, and its variables and secrets apply to that job
only. A workflow that names an environment the repository does not have creates it, with no rules.

Replace repo-id with the repository's id and production with the environment's name.

## Prerequisites

- `ci:PutEnvironment` on the repository (`rn:ews::<organization id>:ci:repository/<repository id>`)
  to create an environment or change its rules; `ci:ListEnvironments` to list them;
  `ci:DeleteEnvironment` to delete one.
- The IAM user ids of the reviewers, from your organization.

## Set the rules

| Field                    | Effect                                                                                                                                        |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `deploymentBranchPolicy` | `all` (the default): any ref. `protected`: only branches a branch protection rule covers. `custom`: only refs that match `deploymentPatterns` |
| `deploymentPatterns`     | Up to 50 `{ "type": "branch" \| "tag", "pattern": "release/*" }`; a branch pattern never admits a tag, nor a tag pattern a branch             |
| `reviewers`              | Up to six IAM users of your organization; one of them must approve each job                                                                   |
| `preventSelfReview`      | The person who started the run cannot approve it                                                                                              |
| `waitTimerMinutes`       | Minutes the job waits, counted from when it reaches the environment, 0 to 43,200                                                              |
| `url`                    | A URL stored with the environment and returned by `ci environments list`                                                                      |

The console has no page for environments; it shows the jobs waiting at one on the run's page.

**CLI**
```sh
dcloud ci environments put repo-id production \
  --deployment-branch-policy protected \
  --reviewers iam-user-id --prevent-self-review
```

**API**
```http
PUT /ci/api/repositories/repo-id/environments/production
{
  "deploymentBranchPolicy": "custom",
  "deploymentPatterns": [{ "type": "branch", "pattern": "release/*" }],
  "reviewers": ["3f0c9a52-5d0e-4c1a-9d39-0b8a3e0f6a11"],
  "preventSelfReview": true
}
```

The answer is `200` with the environment, whether it was created or changed. A field you leave out
keeps its value; a new environment starts with policy `all`, no reviewers and no timer.

- `400` "Invalid environment name" for a name with quotes, backticks, commas, semicolons,
  backslashes or control characters.
- `400` "Reviewer … is not a user of this organization".
- `400` "A custom deployment policy needs at least one branch or tag pattern" when the request sets
  `custom` without `deploymentPatterns`, even if the environment has patterns already.

## Result

For a job of the environment in a run planned after the change:

- **On a ref the policy does not admit**, the job fails with "Branch "feature-x" is not allowed to
  deploy to production due to environment protection rules." (or "Tag "…""). On the
  one-machine-per-run hosted machines it fails at its only step, `Environment protection rules`.
- **With reviewers or a timer**, the job waits while nobody has decided, or while its timer runs.
  The timer runs from the job's arrival, at the same time as the review. Approve or reject it as in
  [Review a deployment](review-a-deployment.md).

Where the job waits depends on where it runs:

- On the one-machine-per-run hosted machines, the job starts and its first step,
  `Wait for production protection rules`, waits and prints who it waits for. The run's two-hour
  limit still applies and ends a longer wait.
- On your own runners and runner pools, the job is not handed to any machine until it may go on, so
  nothing of the environment reaches a machine before then. A job nobody reviews within 5 h 30 min
  expires.

An unapproved job gets no OIDC token even if it asks for one.

An environment's secrets are those of the secrets environment with the same slug (see
[Give a job a secret](give-a-job-a-secret.md)). On the hosted machines, a job of an environment
with reviewers that reads such secrets fails at its step `Environment protection rules`, because
every job of a run runs side by side there; deploy with an OIDC token instead (see
[Deploy with an OIDC token](deploy-with-oidc.md)).

## Delete an environment

```sh
dcloud ci environments delete repo-id production
```

Its variables and approvals go with it. A workflow that names it again creates it again, without
rules.

## Related

- [Review a deployment](review-a-deployment.md)
- [Set a variable](set-a-variable.md)
- `ci.environments.put` · `dcloud ci environments put`
