---
title: Change Requests
---

import VideoContent from '@site/src/components/VideoContent.jsx';

:::note Availability

**Plan**: [Enterprise](https://www.getunleash.io/pricing) | **Version**: `4.19+`

:::

## Overview

Change requests allow you to require an additional approval step before any changes can be made in an environment. This functionality supports the "four-eyes principle", ensuring compliance in industries with strict legal or regulatory requirements.

Change requests also allow you to group changes and [apply them at a specific point in time](#scheduled-change-requests).

Change requests can be enabled for a specific environment within a project, or configured globally for an environment across all projects. This allows you to differentiate your configurations across different environments, such as production and development.

You can require up to 10 approvals for a change request.

<VideoContent videoUrls={["https://www.youtube.com/embed/ENUqFVcdr-w"]}/>

## Change request permissions

Anyone with project access can create a change request; however, only users with specific permissions can approve, apply, or skip them. None of the predefined roles have any change request permissions, so you must create [custom project roles](/reference/rbac#custom-project-roles).

The **skip change requests** [permission](/reference/rbac#environment-permissions) allows users to bypass the change request flow. With this permission in place, you can quickly turn a flag on or off in case you experience issues with a release. This permission alone does not grant access to any other resource, so the user still needs additional permissions, such as to turn a flag on or off.

Admin users also see the change request flow, but they can approve and apply their own changes.

## Enable change requests for a project and environment

To enable change requests for a project, do the following:

1. Open the project and go to **Settings > Change request configuration**.
2. Toggle **Status** for the environment where you want to enable change requests.
3. Select the required number of approvals.

![Change request configuration](/img/change-request-configuration.png)

## Change request flow

Once change requests are enabled for a project and environment, you cannot directly change the status and configuration of a feature flag. Instead, changes are grouped into a change request draft.

![Change request overview](/img/change-request-overview.svg)

Once you make the first modification in an environment that has change requests enabled, any subsequent changes must be added to the same draft. This draft remains private to its author until it's submitted for review. While a draft is active, a banner at the top of the screen informs the author that changes are pending.

A change request can go through the following states:
* **Draft** - The change request is pending, only visible to the author, and can still be edited.
* **In review** - The change request has been submitted for review. The author can still make edits, but doing so will revoke any existing approvals.
* **Approved** - The change request has received the required number of approvals.
* **Scheduled** - The change request is scheduled to be applied at a future time (assuming no [conflicts](#scheduling-errors)).
* **Applied** - The changes have been successfully applied to the environment.
* **Cancelled** - The change request has been canceled by the author or by an admin.
* **Rejected** - The change request has been rejected by a reviewer or by an admin.

Once submitted, the change request appears in the project's **Change requests** tab. From there, you can view details of the proposed changes, the current status of the request, and the next steps required. Users with sufficient permissions can approve or reject, and apply or [schedule](#scheduled-change-requests) the changes.

## Scheduled change requests

:::note Availability

**Plan**: [Enterprise](https://www.getunleash.io/pricing) | **Version**: `5.10+`

:::

When a change request is approved, you can schedule it to be applied later. This allows you to group and apply them at a specific time, such as during a maintenance window or periods of low traffic.

Scheduled changes can be rescheduled, applied immediately, or rejected, but they cannot be edited or moved back to a previous state.

Scheduling changes using change requests gives you a centralized view of changes across multiple flags and strategies, making it easy to reschedule or reject them. However, [potential conflicts](#scheduling-errors) can cause the scheduling to fail.

Alternatively, you can use constraints or segments with the `DATE_AFTER` [operator](/reference/activation-strategies#date-and-time-operators). This approach avoids conflicts, ensures SDKs are aware of changes in advance, and allows them to apply the changes even if they temporarily fail to connect to Unleash.

### Scheduling errors

Unleash suspends a scheduled change request if:
- The change request includes updates to a flag that has been archived or a strategy that has been deleted.
- The change request includes a strategy, segment, or variant that has been updated.
- The user who scheduled a change request is deleted from the users list before the scheduled time.

You must manually review suspended change requests to reschedule, apply, or reject them.

For any suspended or failed change requests, Unleash sends out email notifications to the change request author and to the person who scheduled the change request. Additionally, Unleash displays warnings for flag or strategy deletions that conflict with existing scheduled change requests.

If Unleash fails to apply a scheduled change request, the change request remains in the scheduled state. You can either reschedule and attempt to apply it again or reject it.

If a change request is scheduled and change requests are later disabled for the project or environment, the request will still be applied as scheduled. To prevent this, you must reject the scheduled change request.

## Change requests for segments

:::note Availability

**Plan**: [Enterprise](https://www.getunleash.io/pricing) | **Version**: `5.4+`

:::

Changes to project [segments](/reference/segments), unlike global segments, also go through the change request process.

While change requests are environment-specific, project segments are not. For this reason, Unleash allows you to attach segment changes to any environment where change requests are enabled. By default, Unleash selects the first available environment with change requests enabled, prioritizing [production](/reference/environments#environment-types) environments.

Only Admin users can bypass the change request process for project segments through API calls.

## Environment-level change requests

:::note Availability

**Plan**: [Enterprise](https://www.getunleash.io/pricing) | **Version**: `6.10+`

:::

You can preconfigure change request requirements at the environment level. When configured, all new projects automatically inherit these approval requirements for the specified environments.

You can use environment-level change requests in two ways:

* **As defaults**: Set default approvals per environment, but allow project [Owners](/reference/rbac#projects#predefined-roles) and users with [project update permissions](/reference/rbac#projects) to override the defaults within their projects.
* **As enforced requirements**: Set mandatory approvals for a given environment across all projects. To fully enforce this in a project, ensure that the project has no Owner or users with project update permissions—this prevents any change request modifications at the project level.

You can predefine environment-level change requests when creating or editing an environment in **Configure > Environments**.

![Environment-level change requests](/img/environment-level-change-requests.png)

## Change request preview

To verify a change request, you can preview the changes in [Playground](/reference/playground) by clicking **Preview changes**. You can adjust [Unleash context](/reference/playground#the-unleash-context), but the project and environment remain fixed as they are determined by the change request.

You can only preview a change request in **In Review**, **Approved**, or **Scheduled** states.
