Change Requests
Plan: Enterprise | 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 allows you to group changes and apply them at a specific point in time.
Change requests can be enabled on a per-project and per-environment basis. This allows you to differentiate your configurations across different environments, such as production and development.
You can require up to 10 approvals for change request. Anyone with project access can create a change request; however, only users with the 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. A user cannot approve their own change request.
Enable change request for a project and environment
To enable change requests for a project, do the following:
- Open the project and go to Settings > Change request configuration.
- Toggle Status for the enviroment where you want to enable change requests.
- Select the required number of approvals.
Change request flow
Once a change request 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.
The lifecycle of a change request includes:
- Draft - The change request is in draft mode, and can be edited by the author.
- In review - The request has been submitted for review. The author can still make edits, but doing so will revoke any existing approvals.
- Approved - The request has received the required number of approvals.
- Scheduled - The request is scheduled to be applied at a future time (assuming no conflicts).
- Applied - The changes have been successfully applied to the environment.
- Cancelled - The change request has been cancelled 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 persmissions can approve or reject, and apply or schedule the changes.
Schedule a change
Plan: Enterprise | Version: 5.10+
When a change request is approved, you can schedule it to be applied at a later time. This allows you to group changes together and apply them at a time that is convenient for you, such as during a maintenance window, or at a time when you know there will be less traffic to your application.
Scheduled changes can be rescheduled, applied immediately, or rejected. They can not be edited or moved back to any of the previous states.
When a scheduled change request is applied, the person who scheduled it and the person who created it each receive a notification.
Conflicts
If a change request contains changes that affect a flag that has been archived or a strategy that has been deleted, the change request can not be applied. Unleash warns you ahead of time if you make changes that conflict with a scheduled change request.
Further, if a strategy, project segment, or environment-level variant configuration that is updated in a scheduled change request is updated before the scheduled application time (for instance by a different change request being applied or by updates that circumvent the change request flow), Unleash will suspend the scheduled change request.
The reason for this is that the scheduled change request would overwrite the recent changes made to the strategy, segment, or environment variants. This could cause unwanted changes to occur, so we require you to take manual action.
If a change request has been suspended because a strategy, segment, or environment-level variant configuration has been updated, you can still reschedule, apply, or reject the change request. Any of these actions will put the change request back into the regular flow. You cannot edit the changes of a scheduled change request, so if you want to include the recent changes with the changes in your scheduled change request, you will need to create a new change request.
Again, please be aware that if a strategy, segment, or environment variants affected by a scheduled change request are updated after the change request was scheduled, the application of the scheduled change request will overwrite those changes with the state in the scheduled change request.
If you make one of the changes mentioned in this section, Unleash send out emails to the change request author and to the person who scheduled the change request, letting them know what has happened.
Application failure
If Unleash fails to apply a scheduled change request, the change request will remain in the scheduled state. You can reschedule it and try to apply it again later, or you can reject it. Note that if a strategy in the change request has been deleted or a flag has been archived, the change request can not be applied, so rescheduling it will not help. In these cases, you can either reject the change request, or if the flag has been archived, revive the flag and reschedule it.
If a scheduled change request can not be applied, Unleash will send a notification to the person who scheduled it and to the person who created the change request.
Edge cases: what happens when ...?
If the user who scheduled a change request is deleted from the Unleash users list before the scheduled time, the changes will not be applied. Instead, the schedule will be put into a special suspended state. A change request with suspended schedule will not be applied at its scheduled time. A user with the required permission can reschedule, apply, or reject the change request. Any of these actions will put the change request back into the regular flow.
If a change request has been scheduled and change requests are then disabled for the project and environment, the change request will still be applied according to schedule. To prevent this, you can reject the scheduled change request.
Different ways to schedule changes
Unleash currently offers two distinct ways to schedule changes. Each method has its own pros and cons, and you can also combine the methods for maximum flexibility.
The first method is through scheduled change requests, as we have explained in the preceding sections. Scheduled change requests make it easy to see all the changes across multiple flags and strategies in one view and makes it easy to reschedule or reject them. However, because scheduled changes rely on flags and strategy configurations, conflicts can arise causing the schedule to fail.
The second method uses Unleash's constraints and the DATE_AFTER operator to encode when changes should take effect. The pros of this method is that because these changes can be applied immediately, you won't run into any conflicts when they happen. The cons are that you'll need to apply the same constraints to all the parts that you want to change and that there is no easy way to see all the changes in one view. You also can not scheduled changes to a segment in this way. When using this option, we recommend that you use segments if you want to schedule multiple changes, so that their application time stays in sync.
Another important distinction is how these changes affect your connected SDKs. If you use constraints (or segments), then any connected SDK will be aware of the schedule ahead of time. That means that even if the SDK can not connect to Unleash at the scheduled time, it will still activate the changes because it's encoded in its constraints. On the other hand, if you use change requests to schedule changes, SDKs must update their configuration after the scheduled time to be aware of the changes.
Circumventing change requests
The skip change requests permission allows users to bypass the change request flow. Users with this permission can change feature flags directly (they are of course still limited by any other permissions they have).
The skip change requests permission was designed to make it possible to quickly turn something off in the event that a feature release didn't go as expected or was causing issues.
The skip change requests permission does not grant any other permissions, so to be allowed to do things as enabling/disabling a flag, the user will still need the explicit permissions to do that too.
In the UI non-admin users with skip change requests permission and explicit permission to perform the actual action will be able to make changes directly without change requests.
Admin users will always see the change request UI so that they can test the change request flow. Admin users can however self-approve and self-apply their own changes.
Change Request for segments
Plan: Enterprise | Version: 5.4+
Changes to project segments (as opposed to global segments) also go through the change request process. This is to prevent a backdoor in the change request process.
Since projects segments are not environment specific and change requests are always environment specific we allow to attach segment change to any environment with change requests enabled. When you make changes though the Change Request UI it will automatically select first environment with change requests enabled, giving priority to production environments.
Changes to segments can be only circumvented by admin users through the API calls.
Change Request Preview Playground
To verify that a change request is correct, you can preview the result of change request's application in a change request playground.
From the change request overview page, go to the corresponding playground and evaluate all your flags in the project and environment that your change request applies too.
Unleash context can be adjusted in the same way as in a regular playground, but the project and environment cannot be changed as they are derived from the change request itself. Once the evaluation results confirm the changes in your change request are correct, go back to the change request overview and proceed with the approval or rejection.
Change request preview simulates the application of changes in a non-persistent transaction. You still need to apply the changes to persist them for the SDKs to see the changes. A change request can only be previewed when the change request is In Review, Approved, or Scheduled. It cannot be previewed when the change request is in Draft, Applied, Cancelled, or Rejected status.
Change request preview does not require special permissions like approve/reject change requests or apply change requests. It allows more users to provide feedback on the correctness of the changes.