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.
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. When you add an approver to a change request, they are notified by email.
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.
The skip change requests permission 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.
To enable change requests for a project, do the following:
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.
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:
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 the changes.
The change request overview provides a centralized view of all your change requests across all projects in a single location. This helps you track and manage change requests without navigating between individual projects.
To access the overview, go to Change requests in the main navigation menu.
The overview table displays both open and closed change requests, allowing you to see the status and details of all changes at a glance.
You can filter the table to show specific subsets of change requests:
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 can cause the scheduling to fail.
Alternatively, you can use constraints or segments with the DATE_AFTER operator. 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.
Unleash suspends a scheduled change request if:
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.
Changes to project 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 environments.
Only Admin users can bypass the change request process for project segments through API calls.
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:
You can predefine environment-level change requests when creating or editing an environment in Configure > Environments.
To verify a change request, you can preview the changes in Playground by clicking Preview changes. You can adjust 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.