# Change requests

A change request lets you change secrets in an environment you don't have write access to. A typical case: a developer with access to `dev` needs a new variable in `prod` for a release. They propose the change, and a `prod` editor reviews it, approves it, and applies it.

> **Info.** Available only with a [subscription](https://tuna.am/#pricing).

Requests work only in the [dashboard](https://my.tuna.am/secrets/requests). You can't create or approve them through the API, CLI, or service keys: approval has to come from a person, not from a leaked key or a script.

Environment editors can still edit secrets directly. Requests and policies don't forbid direct edits; they add a path for those who don't have write access.

## Who can do what

| Action                      | Who can                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| Create a request            | any project member, even without access to the target environment                          |
| See values in a request     | a member with access to the environment, or the author of the value                        |
| Approve and apply           | an environment editor: a member with write access to it, as well as team admins and owners |
| Configure approval policies | team admins and owners                                                                     |

Members' permissions for environments are set in [team roles](https://tuna.am/en/docs/team/roles.md).

## How to propose a change

Open a configuration. If you don't have write access to it, you'll see **Propose change** instead of the **Save** button.

![The dev configuration without write access: the Propose change button in the top right corner](/docs/img/secrets/change-requests/config-viewer.webp)

You put the request together in a form:

1. Enter a title and, optionally, a description of why the change is needed.
2. Select a project and a configuration. Environments you don't have access to are marked with a lock: you can change secrets in them, but you won't see the current values or secret names.
3. Add or change secrets. Each configuration is a separate block that is approved and applied separately. To change secrets in several environments, click **Add configuration**.
4. Click **Preview**: it shows what will change, and you can pick reviewers there. Without reviewers, the request waits for everyone who can approve it.
5. Click **Submit for review**.

![The new request form: title, description, project, and a prod configuration block with a new variable](/docs/img/secrets/change-requests/form-filled.webp)

A request can't change secrets with `restricted` visibility or set that visibility.

Reviewers get an email. It contains the request title, the project, the configurations, and the secret names, but no values.

## Review and apply

Requests waiting for your review show up on the dashboard home page in the **Needs attention** block and in **Secrets → Change requests** with the **Awaiting my review** filter.

![The list of change requests with a Review button next to a request waiting for approval](/docs/img/secrets/change-requests/list-review.webp)

On the request page, each block shows its diff and approvals. Values are hidden: click the eye icon to see them. An environment editor sees both the old values and the new ones.

![A prod block under review: new and changed secrets, the Approve button, and an inactive Apply button](/docs/img/secrets/change-requests/request-review.webp)

1. Click **Approve**. Changed your mind? Click **Withdraw approval**.
2. Once the block is approved, click **Apply** and confirm. The new values are written to the configuration right away, and an entry with a link to the request appears in the [change history](https://tuna.am/en/docs/secrets.md#history).

![An applied block: who applied the changes and when, and a link to the configuration history](/docs/img/secrets/change-requests/request-applied.webp)

The author gets an email when the changes are applied or the request is closed.

If you no longer need the request, click **Close request**. The author and reviewers can edit the request while it's open, but editing a block resets its approvals and the review starts over.

### Statuses

| Status            | Meaning                                                |
| ----------------- | ------------------------------------------------------ |
| Draft             | the request is saved but not submitted for review      |
| In review         | waiting for approval                                   |
| Approved          | there are enough approvals, the changes can be applied |
| Applied           | the changes are written to the configuration           |
| Partially applied | some blocks are applied, the rest are canceled         |
| Canceled          | the request was closed without being applied           |

### If a secret was changed directly

Changes are applied strictly. If someone changed the same secret directly after the request was created, the block is marked **Outdated** and can't be applied: otherwise the request would silently overwrite someone else's edit. Click **refresh** to rebuild the block from the current values. This resets the approvals.

![A block marked Outdated: secrets changed after creation, with a refresh link](/docs/img/secrets/change-requests/request-outdated.webp)

A configuration with an open request shows a banner with a link to it, so editors can see that changes are already waiting for review.

## Approval policies

By default, a block can be applied after one approval from an environment editor. Approval policies set stricter rules, for example two approvals for `prod` and a ban on approving your own request. Team admins and owners manage policies in [Secrets → Approval policies](https://my.tuna.am/secrets/policies).

![The form for a new Production policy: two approvals from any environment editor, and the author can't approve their own request](/docs/img/secrets/change-requests/policy-form.webp)

A policy defines:

* **Scope** — all team projects, including new ones, or selected projects. Within a project, you can limit the policy to environments (together with their child configurations) or to individual configurations.
* **Rules** — how many approvals are needed, from 1 to 20, and whose approvals count: any environment editor or selected members. An approval counts only if the member has write access to the environment. All rules of the policy must be met.
* **The request author can't approve it** — the author's approval doesn't count, and the **Approve** button is unavailable to them.
* **Assign members from the rules as reviewers** — when a request is created, they become reviewers and get an email.

If several policies apply to a configuration, all of them must be met. A block under a policy gets a progress badge, for example `0/2`, and the **Apply** button becomes available once all rules are met.

![A block under a policy: the 0/2 badge and a hint on the Apply button](/docs/img/secrets/change-requests/request-policy.webp)

## How long requests are kept

Closed and applied requests are kept as long as the configuration [change history](https://tuna.am/en/docs/secrets.md#history) on your plan. Open requests aren't deleted. If you delete a configuration or an environment, its blocks disappear from requests. If you delete a project, its requests are deleted too.