Change approvals in Feature Experimentation

Change approvals improve control and reduce risk in software releases by requiring a review of feature flag changes before they launch. Approvers review each change before it goes live. A clear approval process helps your team run experiments and ship features efficiently.

You can tailor approvals to how your organization works:

• Team-based approvers and watchers – Assign a team so that any member can approve, and roster changes apply automatically.
• Multiple approval policies – Set a baseline policy for an environment and route specific flags to their own approvers.
• Scheduled changes with approvals – Submit a scheduled flag change through the approval workflow so planned deployments follow your governance process.
• Webhooks – Notify external issue tracking or continuous integration and continuous delivery (CI/CD) tools when a change request opens, then approve or reject from those tools.
• REST API – Manage approval policies, approvers, and watchers programmatically. Refer to the Feature Experimentation REST API reference for endpoint details and authentication.

Approval policies

An approval policy defines which change surfaces require approval, who approves, and who receives notifications. You can apply a default approval policy to every flag in an environment, then override it with custom policies only for the flags that need different approvers. Optimizely supports two policy types:

• Environment-level policy – Applies baseline approval rules to all flags in an environment. Every flag inherits these rules automatically unless a custom policy overrides them.
• Custom policy – Applies approval rules to a targeted set of flags. A custom policy takes priority over the environment-level policy for the flags it covers.

Change surfaces

Change surfaces are the actions that trigger a review. Policies gate changes to a flag's rules and ruleset, not the flag definition (such as variables). Select the surfaces that require approval when you create a policy:

• Ruleset – Run or pause the ruleset, change the order of rules, or modify the Everyone Else variation.
• Rules – Run, pause, or conclude a rule, or delete a rule. See Manage rules.
• Audiences – Add, remove, or modify the audience selected on a rule. This gates the audience selection, not edits to the audience definition.
• Traffic Allocation (%) – Modify the traffic allocation percentage.
• Metrics – Add, remove, or modify a metric on a rule. See Choose metrics in Feature Experimentation.
• Variations – Add, remove, or modify variation selections on a rule, or modify variation traffic distribution percentages. This gates variation selections within a rule, not the flag variation definition, such as variables. See Flag variations and flag variables overview.

Create a change approval policy

You can create an approval policy to define which change surfaces require review and who approves. Create an environment-level baseline for every flag in an environment, a custom policy for a targeted set of flags, or both.

The Change Approval Policies page lists every existing policy with its name, environment, type, flags, change surfaces, and created date. You can filter the list by environment, or search by name.

1. Go to Settings > Change Approval Policies. The minimum permissions required to configure approvals is "Administrator" on the environment. See Manage environment roles in Feature Experimentation.
2. Click Create Approval Policy and select a policy type:
   • Custom Approval Policy – Define custom approval rules for a targeted set of flags in an environment. Custom policies take priority over any environment-level policies in place.

   • [ENVIRONMENT_NAME] Environment Policy – Apply baseline approval rules to all flags in that environment, such as Production Environment Policy or Development Environment Policy.

     

3. Enter a Name and an optional Description.

4. For a custom policy, select the Environment the policy applies to. An environment-level policy already targets its own environment. You cannot change the environment after you create the approval policy.

   

5. For a custom policy, search for and add the Flags that require approval. You cannot add a flag that already belongs to another custom policy. See Manage flags.

6. Under Change Surfaces, select the surfaces that require approval.

   

7. Under Approvers, add who approves the changes:
   • In a custom policy, search for and add the teams or users who approve or reject change requests. See Configure teams in Feature Experimentation.
   • In an environment-level policy, choose Assign approvals to flag owner, Assign approvals to flag team(s), or Select approvers to add specific teams or users. See Assign teams as approvers or watchers.

8. (Optional) Under Watchers, search for and add teams or users who receive notifications but cannot approve changes.

   

9. Click Save.

You can edit a policy or duplicate it from the Change Approval Policies page. To do so, click More Options (...) > Edit or Duplicate. When you change a policy's approvers, every open change request for that policy immediately adopts the new approvers.

Assign teams as approvers or watchers

Assign a team instead of individuals to avoid maintaining approver lists as membership changes. In the Approvers or Watchers field of any policy, search for a team and add it.

• Any member can approve – Any current member can approve a change request. After one member approves, the request is complete.
• Roster changes apply automatically – When someone joins or leaves the team, their approval eligibility updates within a few minutes, with no policy edit needed.

To set up teams and roles, see Granular roles and permissions. To manage individual users, see Manage collaborators in Feature Experimentation.

Submit an approval request

When you want to make a change that requires approval, complete the following:

1. Edit a feature flag as needed.

2. Click Preview Changes. After approvals are set up, you cannot apply changes without a review.

   

3. Click Show Details to see the proposed changes displayed in a diff format.
4. Enter a reason for the changes. This helps approvers understand the context and necessity of the changes.
5. Click Submit for approval.

After you submit, approvers receive an email. The flag is then locked until the request clears, so what approvers review is exactly what ships.

Schedule a change that requires approval

Schedule a flag change to run at a future time while you still follow your approval process. Scheduled changes and change approvals work together in the same environment.

Whether a scheduled change requires approval depends on the environment's policies. Policies apply to rule edits, so you can schedule three operations:

• Rule status – Pause or run a rule.
• Percentage rollout – Change the traffic percentage or the selected variations within a rule.
• Audience conditions – Change which audience a rule targets.

You cannot schedule edits to flag variations, variables, or metrics.

Create a scheduled change

1. Open the flag and create a scheduled change.
2. Choose a supported operation.
3. Set the date and time for the change to run.
4. Enter a reason. A reason is required when the change requires approval.
5. Submit the scheduled change.

When the change requires approval, it is created with a Pending status and enters the approval workflow. It appears in both the Scheduled Changes list and the Approvals dashboard. When it does not require approval, it is saved with an N/A status. It runs at the scheduled time without a review.

Submit multiple scheduled changes that require approval for the same flag and environment. Unlike immediate changes, a pending scheduled change does not lock the flag. Keep editing or submit immediate changes while it is queued. The limit of one pending immediate change per flag and environment still applies.

Track scheduled changes

Each row in the Scheduled Changes list shows an approval status of Pending, Approved, or N/A. Filter the list by All, Pending, or Approved. Changes in a final state (rejected, withdrawn, or auto-rejected) move to the history on the Approvals dashboard.

Edit, cancel, or delete a scheduled change

You cannot edit a scheduled change after you submit it. To change the date, time, or operation, delete it and create another.

• Pending change – Only the creator can delete it. Deleting withdraws the request, cancels the scheduled job, and notifies approvers.
• Approved change – Cancel it before it runs. Approvers are not notified. Within the short window before the scheduled time, you can no longer cancel it, and a message explains why.

If a scheduled change is still awaiting approval at its scheduled time, it is rejected automatically and does not run. The requester is notified, and the reason appears in the history on the Approvals dashboard.

View pending requests

Track requests that await review, and withdraw your own if plans change. After you send an approval request, Optimizely locks the flag configuration until an approver reviews it.

1. Go to Flags > Approvals to view pending change requests. The blue number indicates the count of pending change requests that require review.

   

2. (Optional) Filter requests according to the Environment, Status, and Archived.
3. Select More Options (...) > View / Withdraw to view or withdraw a change request you submitted. Only the author of a change request can withdraw the request.

Review approval requests

Review a request and approve or reject it before the change goes live. You can add yourself as an approver before you review requests. When a team is the approver, any current member can review.

1. Go to Flags > Approvals to view pending approvals.

2. Click the approval link, or select More options > View, to open the request details.

   

3. Review the details to understand what changed. For a scheduled change, the request displays the scheduled execution time.

4. Approve or reject the request. When you approve, Optimizely applies the change immediately, or at the scheduled time for a scheduled change. If you reject the request, provide feedback that explains the decision.

   

You cannot approve your own change request, so a separate approver keeps a second set of eyes on every change. An approver cannot edit a pending request, only approve or reject it. When another team member approves a request, it shows as handled so you do not duplicate effort.

To review who approved past changes and when, see Change history in Feature Experimentation.

Configure webhooks

You can send change approval events to external systems, such as issue tracking or CI/CD tools, so your team stays informed of approval activity. A webhook fires when a change request is created, updated, or archived, and links back to Optimizely to review and act on the request.

To set up a webhook and interpret its payload, see Change approval webhooks.

Email notifications

Approvers receive email notifications by default, and you can add teams or users as watchers to notify them too. Emails go out when approvals are set up and when a change request is submitted, withdrawn, approved, or rejected. When a team becomes an approver, its members are emailed the flags they can approve.