From c85d17e203e49faa86721de4f0d2e92a68e11a59 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Fri, 3 Jul 2026 14:14:19 +0200 Subject: [PATCH 01/20] change requests --- website/docs/change-requests.mdx | 152 +++++++++++++++++++++++++++++++ website/sidebars.ts | 1 + website/src/pages/index.js | 1 + 3 files changed, 154 insertions(+) create mode 100644 website/docs/change-requests.mdx diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx new file mode 100644 index 00000000..7a6ddb40 --- /dev/null +++ b/website/docs/change-requests.mdx @@ -0,0 +1,152 @@ +--- +id: change-requests +title: Change Requests & Scheduled Changes (Beta) +description: Propose, schedule, and review feature flag changes with the ConfigCat approval flow. +--- + +:::info +**Beta Feature**: Change Requests & Scheduled Changes is in closed beta. We're now collecting feedback from real-world usage to fine-tune the experience. +::: + +A _Change Request_ is a bundle of feature flag changes that you prepare on the Dashboard without publishing them immediately. +You can propose a change for manual publishing later, or schedule it to be applied automatically at a specific time. + +Typical use cases: + +- **Scheduled release** - you want a feature turned on next Monday at 9 AM without being at your desk. +- **Approval before go-live** - you work in a regulated environment where a colleague must review every change before it reaches production. +- **Draft and collaborate** - you want to prepare changes, collect feedback in comments, and only publish when the team agrees. + +## How does it work? + +Feature flag changes in ConfigCat can be: + +- **Published immediately** - the classic way, the change takes effect right away. +- **Proposed** - saved as a change request for later manual publishing. +- **Scheduled** - saved as a change request that ConfigCat applies automatically at a selected date and time. + +If an environment is configured as _approval-required_, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled change request is only applied on schedule if it has been approved. + +## Permissions + +### Who can create change requests? + +Only members with **Read/Write** (feature management) permission in the environment can propose or schedule changes. + +### Approval flow product preference + +The **Approval flow** product preference controls which environments require approval. + +You can enable it: +- for the entire product, or +- per environment. + +When an environment is approval-required, all feature flag changes must go through a change request. The only exception is the **Can bypass approval** permission, described below. + +### Change request approvals permission + +Permission groups include a **Change request approvals** permission with the following values: + +- **Cannot approve** - The member cannot approve any change request. +- **Can approve others** - The member can approve change requests opened by other members. +- **Can bypass approval** - The member can approve any change request, or apply changes directly without going through the approval flow. + +This permission can be set product-wide or overridden per environment. + +In approval-required environments: +- Members with **Read/Write** can create change requests (propose or schedule changes). +- Members with at least **Can approve others** can approve change requests. +- Members with **Read/Write** can apply an approved change request. +- Members with **Can bypass approval** can approve any change request, or apply changes directly, skipping the approval step entirely. +- Members with at least **Can approve others** can close any change request. + +:::note +**Can bypass approval** is intended for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in — it is never automatic. + +For scheduled change requests specifically, a member with **Can bypass approval** can configure a given scheduled change request to be applied on schedule without requiring prior approval. This opt-in must be set per change request. +::: + +## Lifecycle of a change request + +### Ownership and editing + +A change request can only be edited by its owner. Other members can: +- comment on the request, +- approve it (if they have the appropriate permission), +- close it (if they have at least **Can approve others**). + +### Comments, notifications, and activity + +Each change request supports comments for team discussion. Email notifications are sent for important events (approvals, comments, status changes). The activity log records everything that happened on the request. + +### Re-approval after edits + +If the owner edits a change request — for example, modifying the feature flag values or changing the schedule — all existing approvals are dropped. The request must be reviewed and approved again before it can be applied. + +## Statuses + +- **Open** - The change request has been created and is waiting to be applied. +- **Applied** - The changes have been published. +- **Closed** - The change request was closed without being applied. Closed change requests cannot be reopened. + +### Scheduled request fallback + +If a scheduled change request cannot be applied at the planned time — for example, because it was never approved — the schedule is removed and the request becomes a regular open (proposed) change request. You can then fix the issue and apply it manually or even re-schedule it. + +### Needs approval + +A change request shows **Needs approval** when it is in an approval-required environment and has not yet been approved. + +### Needs attention + +A change request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can proceed. + +Possible causes: + +- **Conflicting changes** — changes for the same feature flags have been published since the change request was opened. See [Conflict handling](#conflict-handling). +- **Owner is unavailable** — the owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the change request. +- **Missing mandatory notes** — mandatory notes were enabled on the environment after the change request was created, and the change request does not have notes. +- **Circular dependency** — a change was published since the change request was opened, and applying the request now would create a circular dependency through prerequisite flags. + +## Conflict handling + +When you open a change request, ConfigCat notifies you if any other open change request already includes the same feature flags. + +This matters because if two change requests modify the same flag, the one applied first will mark the other as invalid. An invalid change request cannot be applied until its conflicts are resolved. + +The conflict resolver shows you: +- the changes your change request proposes, and +- the changes that have been published since you opened it. + +You can resolve conflicts using one of the following options: + +### Auto merge + +Automatically merges your proposed changes with the currently published state. This option is only available when the system is able to merge the changes safely. + +:::tip +Always review the merged result carefully before applying to make sure it reflects the correct values. +::: + +### Accept theirs and re-apply your changes + +Starts resolving the conflict from the currently published values, then lets you re-apply your intended changes on top. Use this when you want your changes applied to the current state of the flag. This is the recommended option when Auto merge is not available. + +### Accept yours and re-apply the published changes + +Starts from your proposed values, then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal. + +### Remove setting from change request + +Removes this particular feature flag from the change request, discarding its changes. This option is only available when the change request contains more than one feature flag. + +### Close change request + +Closes the entire change request. Use this when the conflict should not be resolved and the changes should not be applied at all. + +## Current limitations + +The approval flow currently applies to feature flag value changes only. The following actions do not require a change request or approval: + +- Creating or deleting a feature flag. +- Changes to segments. diff --git a/website/sidebars.ts b/website/sidebars.ts index 27693277..620c6a3f 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -37,6 +37,7 @@ const docs: SidebarConfig = [ ], }, 'advanced/predefined-variations', + 'change-requests', ], }, { diff --git a/website/src/pages/index.js b/website/src/pages/index.js index f1c133cf..9ed4bfd0 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -17,6 +17,7 @@ const features = [ { url: 'organization', title: 'Organization & Roles' }, { url: 'targeting/targeting-overview', title: 'Targeting' }, { url: 'advanced/predefined-variations', title: 'Predefined Variations vs Free‑Form Values' }, + { url: 'change-requests', title: 'Change Requests & Scheduled Changes (Beta)' }, ], }, { From 2f840935938b8ba57fffe1e6a1a85ce534d89c8d Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Fri, 3 Jul 2026 15:52:35 +0200 Subject: [PATCH 02/20] info --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 7a6ddb40..c93b0ac4 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -60,7 +60,7 @@ In approval-required environments: - Members with **Can bypass approval** can approve any change request, or apply changes directly, skipping the approval step entirely. - Members with at least **Can approve others** can close any change request. -:::note +:::info **Can bypass approval** is intended for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in — it is never automatic. For scheduled change requests specifically, a member with **Can bypass approval** can configure a given scheduled change request to be applied on schedule without requiring prior approval. This opt-in must be set per change request. From dfe897864eb15a10bbd61f328ccfa94a72c0b998 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Mon, 6 Jul 2026 17:38:36 +0200 Subject: [PATCH 03/20] rewording --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index c93b0ac4..b6ca848b 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -49,7 +49,7 @@ Permission groups include a **Change request approvals** permission with the fol - **Cannot approve** - The member cannot approve any change request. - **Can approve others** - The member can approve change requests opened by other members. -- **Can bypass approval** - The member can approve any change request, or apply changes directly without going through the approval flow. +- **Can bypass approval** - The member can approve any change request opened by other members, or apply changes directly without going through the approval flow. This permission can be set product-wide or overridden per environment. From 6c69b48cf8df3904947fc69d3a0084288ee517d5 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Mon, 6 Jul 2026 17:39:18 +0200 Subject: [PATCH 04/20] rewording --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index b6ca848b..ed717799 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -49,7 +49,7 @@ Permission groups include a **Change request approvals** permission with the fol - **Cannot approve** - The member cannot approve any change request. - **Can approve others** - The member can approve change requests opened by other members. -- **Can bypass approval** - The member can approve any change request opened by other members, or apply changes directly without going through the approval flow. +- **Can bypass approval** - The member can approve change request opened by other members, or apply changes directly without going through the approval flow. This permission can be set product-wide or overridden per environment. From 21c2b5afd55dfc479c6e77ddf4643ec690fc2150 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Mon, 6 Jul 2026 18:10:00 +0200 Subject: [PATCH 05/20] fix --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index ed717799..7cf19bde 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -57,7 +57,7 @@ In approval-required environments: - Members with **Read/Write** can create change requests (propose or schedule changes). - Members with at least **Can approve others** can approve change requests. - Members with **Read/Write** can apply an approved change request. -- Members with **Can bypass approval** can approve any change request, or apply changes directly, skipping the approval step entirely. +- Members with **Can bypass approval** can approve change requests, or apply changes directly, skipping the approval step entirely. - Members with at least **Can approve others** can close any change request. :::info From 657bc6b65275960773dbe9a33af1fc7f10b653b1 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Mon, 6 Jul 2026 18:10:27 +0200 Subject: [PATCH 06/20] ul li --- website/docs/change-requests.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 7cf19bde..79333783 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -37,9 +37,7 @@ Only members with **Read/Write** (feature management) permission in the environm The **Approval flow** product preference controls which environments require approval. -You can enable it: -- for the entire product, or -- per environment. +You can enable it for the entire product, or per environment. When an environment is approval-required, all feature flag changes must go through a change request. The only exception is the **Can bypass approval** permission, described below. From d39a472210a2c68fedab87de3a3569926fbfb0f7 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Mon, 6 Jul 2026 18:10:55 +0200 Subject: [PATCH 07/20] fix --- website/docs/change-requests.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 79333783..5a0848ea 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -112,9 +112,7 @@ When you open a change request, ConfigCat notifies you if any other open change This matters because if two change requests modify the same flag, the one applied first will mark the other as invalid. An invalid change request cannot be applied until its conflicts are resolved. -The conflict resolver shows you: -- the changes your change request proposes, and -- the changes that have been published since you opened it. +The conflict resolver shows you the changes your change request proposes, and the changes that have been published since you opened it. You can resolve conflicts using one of the following options: From e6caf15e0e07465e1da87738a445fd244b3b40d8 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Mon, 6 Jul 2026 18:11:43 +0200 Subject: [PATCH 08/20] remove flag --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 5a0848ea..500c4d96 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -132,7 +132,7 @@ Starts resolving the conflict from the currently published values, then lets you Starts from your proposed values, then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal. -### Remove setting from change request +### Remove feature flag from change request Removes this particular feature flag from the change request, discarding its changes. This option is only available when the change request contains more than one feature flag. From e92ae03e675b8371040ef4fd929f1c09c5d4e3d1 Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:12:04 +0200 Subject: [PATCH 09/20] approval flow --- website/docs/change-requests.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 500c4d96..8b32aab6 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -1,7 +1,7 @@ --- id: change-requests -title: Change Requests & Scheduled Changes (Beta) -description: Propose, schedule, and review feature flag changes with the ConfigCat approval flow. +title: Approval Flow & Scheduled Changes (Beta) +description: Propose, schedule, and review feature flag changes with the ConfigCat change requests. --- :::info From a15ab9b4cf171f5ad15373d367f279ccee8a0fd6 Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:17:58 +0200 Subject: [PATCH 10/20] prg --- website/docs/change-requests.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 8b32aab6..e892a076 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -5,11 +5,12 @@ description: Propose, schedule, and review feature flag changes with the ConfigC --- :::info -**Beta Feature**: Change Requests & Scheduled Changes is in closed beta. We're now collecting feedback from real-world usage to fine-tune the experience. +**Beta Feature**: Approval flow & Scheduled Changes is in closed beta. You can join the beta by writing to our support at configcat.com/support. We are collecting feedback from real-world use to improve the experience. ::: -A _Change Request_ is a bundle of feature flag changes that you prepare on the Dashboard without publishing them immediately. -You can propose a change for manual publishing later, or schedule it to be applied automatically at a specific time. +A _Change Request_ is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. +You can propose a change for later manual publishing, or schedule it to be applied automatically at a specific time. +This supports the four-eyes principle, because another person can review and approve the change before it reaches production. Typical use cases: From a015f952627031602f813157745ffa04565a28b8 Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:19:29 +0200 Subject: [PATCH 11/20] prg --- website/docs/change-requests.mdx | 90 ++++++++++++++++---------------- website/src/pages/index.js | 2 +- 2 files changed, 47 insertions(+), 45 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index e892a076..0cad7db2 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -5,92 +5,94 @@ description: Propose, schedule, and review feature flag changes with the ConfigC --- :::info -**Beta Feature**: Approval flow & Scheduled Changes is in closed beta. You can join the beta by writing to our support at configcat.com/support. We are collecting feedback from real-world use to improve the experience. +**Beta Feature**: Approval flow and scheduled changes are in closed beta. You can join the beta by contacting support at configcat.com/support. We are collecting feedback from real-world use to improve the experience. ::: -A _Change Request_ is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. +A change request is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. You can propose a change for later manual publishing, or schedule it to be applied automatically at a specific time. This supports the four-eyes principle, because another person can review and approve the change before it reaches production. Typical use cases: -- **Scheduled release** - you want a feature turned on next Monday at 9 AM without being at your desk. -- **Approval before go-live** - you work in a regulated environment where a colleague must review every change before it reaches production. -- **Draft and collaborate** - you want to prepare changes, collect feedback in comments, and only publish when the team agrees. +- **Scheduled release**: You want a feature turned on next Monday at 9 AM without being at your desk. +- **Approval before go-live**: You work in a regulated environment where a colleague must review every change before it reaches production. +- **Draft and collaborate**: You want to prepare changes, collect feedback in comments, and only publish when the team agrees. ## How does it work? Feature flag changes in ConfigCat can be: -- **Published immediately** - the classic way, the change takes effect right away. -- **Proposed** - saved as a change request for later manual publishing. -- **Scheduled** - saved as a change request that ConfigCat applies automatically at a selected date and time. +- **Published immediately**: The classic way. The change takes effect right away. +- **Proposed**: Saved as a change request for later manual publishing. +- **Scheduled**: Saved as a change request that ConfigCat applies automatically at a selected date and time. -If an environment is configured as _approval-required_, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled change request is only applied on schedule if it has been approved. +If an environment is configured as approval-required, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes. A scheduled change request is only applied on schedule if it has been approved. ## Permissions ### Who can create change requests? -Only members with **Read/Write** (feature management) permission in the environment can propose or schedule changes. +Only members with **Read/Write** permission for feature management in the environment can propose or schedule changes. ### Approval flow product preference The **Approval flow** product preference controls which environments require approval. -You can enable it for the entire product, or per environment. +You can enable it for the whole product or for each environment. When an environment is approval-required, all feature flag changes must go through a change request. The only exception is the **Can bypass approval** permission, described below. ### Change request approvals permission -Permission groups include a **Change request approvals** permission with the following values: +Permission groups include a **Change request approvals** permission with these values: -- **Cannot approve** - The member cannot approve any change request. -- **Can approve others** - The member can approve change requests opened by other members. -- **Can bypass approval** - The member can approve change request opened by other members, or apply changes directly without going through the approval flow. +- **Cannot approve**: The member cannot approve any change request. +- **Can approve others**: The member can approve change requests opened by other members. +- **Can bypass approval**: The member can approve change requests opened by other members, or apply changes directly without going through the approval flow. This permission can be set product-wide or overridden per environment. In approval-required environments: -- Members with **Read/Write** can create change requests (propose or schedule changes). + +- Members with **Read/Write** can create change requests and propose or schedule changes. - Members with at least **Can approve others** can approve change requests. - Members with **Read/Write** can apply an approved change request. -- Members with **Can bypass approval** can approve change requests, or apply changes directly, skipping the approval step entirely. +- Members with **Can bypass approval** can approve change requests or apply changes directly, skipping the approval step. - Members with at least **Can approve others** can close any change request. :::info -**Can bypass approval** is intended for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in — it is never automatic. +**Can bypass approval** is meant for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in. It is never automatic. -For scheduled change requests specifically, a member with **Can bypass approval** can configure a given scheduled change request to be applied on schedule without requiring prior approval. This opt-in must be set per change request. +For scheduled change requests, a member with **Can bypass approval** can choose to apply a scheduled change request on its set date without prior approval. This opt-in must be set for each change request. ::: ## Lifecycle of a change request ### Ownership and editing -A change request can only be edited by its owner. Other members can: -- comment on the request, -- approve it (if they have the appropriate permission), -- close it (if they have at least **Can approve others**). +Only the owner can edit a change request. Other members can: + +- comment on the request +- approve it if they have the right permission +- close it if they have at least **Can approve others** ### Comments, notifications, and activity -Each change request supports comments for team discussion. Email notifications are sent for important events (approvals, comments, status changes). The activity log records everything that happened on the request. +Each change request supports comments for team discussion. Email notifications are sent for important events, such as approvals, comments, and status changes. The activity log records everything that happened on the request. ### Re-approval after edits -If the owner edits a change request — for example, modifying the feature flag values or changing the schedule — all existing approvals are dropped. The request must be reviewed and approved again before it can be applied. +If the owner edits a change request, for example by changing feature flag values or the schedule, all existing approvals are removed. The request must be reviewed and approved again before it can be applied. ## Statuses -- **Open** - The change request has been created and is waiting to be applied. -- **Applied** - The changes have been published. -- **Closed** - The change request was closed without being applied. Closed change requests cannot be reopened. +- **Open**: The change request has been created and is waiting to be applied. +- **Applied**: The changes have been published. +- **Closed**: The change request was closed without being applied. Closed change requests cannot be reopened. ### Scheduled request fallback -If a scheduled change request cannot be applied at the planned time — for example, because it was never approved — the schedule is removed and the request becomes a regular open (proposed) change request. You can then fix the issue and apply it manually or even re-schedule it. +If a scheduled change request cannot be applied at the planned time, for example because it was never approved, the schedule is removed and the request becomes a regular open change request. You can then fix the issue and apply it manually or schedule it again. ### Needs approval @@ -98,48 +100,48 @@ A change request shows **Needs approval** when it is in an approval-required env ### Needs attention -A change request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can proceed. +A change request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can continue. Possible causes: -- **Conflicting changes** — changes for the same feature flags have been published since the change request was opened. See [Conflict handling](#conflict-handling). -- **Owner is unavailable** — the owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the change request. -- **Missing mandatory notes** — mandatory notes were enabled on the environment after the change request was created, and the change request does not have notes. -- **Circular dependency** — a change was published since the change request was opened, and applying the request now would create a circular dependency through prerequisite flags. +- **Conflicting changes**: Changes for the same feature flags were published after the change request was opened. See [Conflict handling](#conflict-handling). +- **Owner is unavailable**: The owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the change request. +- **Missing mandatory notes**: Mandatory notes were enabled on the environment after the change request was created, and the change request does not have notes. +- **Circular dependency**: A change was published after the change request was opened, and applying the request now would create a circular dependency through prerequisite flags. ## Conflict handling -When you open a change request, ConfigCat notifies you if any other open change request already includes the same feature flags. +When you open a change request, ConfigCat notifies you if another open change request already includes the same feature flags. This matters because if two change requests modify the same flag, the one applied first will mark the other as invalid. An invalid change request cannot be applied until its conflicts are resolved. -The conflict resolver shows you the changes your change request proposes, and the changes that have been published since you opened it. +The conflict resolver shows the changes your change request proposes and the changes that were published after you opened it. -You can resolve conflicts using one of the following options: +You can resolve conflicts in one of these ways: ### Auto merge -Automatically merges your proposed changes with the currently published state. This option is only available when the system is able to merge the changes safely. +This option automatically merges your proposed changes with the currently published state. It is only available when the system can merge the changes safely. :::tip -Always review the merged result carefully before applying to make sure it reflects the correct values. +Always review the merged result carefully before applying it to make sure it shows the correct values. ::: ### Accept theirs and re-apply your changes -Starts resolving the conflict from the currently published values, then lets you re-apply your intended changes on top. Use this when you want your changes applied to the current state of the flag. This is the recommended option when Auto merge is not available. +This option starts from the currently published values and then lets you re-apply your intended changes on top. Use this when you want your changes applied to the current state of the flag. This is the recommended option when Auto merge is not available. ### Accept yours and re-apply the published changes -Starts from your proposed values, then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal. +This option starts from your proposed values and then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal. -### Remove feature flag from change request +### Remove feature flag from change request -Removes this particular feature flag from the change request, discarding its changes. This option is only available when the change request contains more than one feature flag. +This removes that feature flag from the change request and discards its changes. This option is only available when the change request contains more than one feature flag. ### Close change request -Closes the entire change request. Use this when the conflict should not be resolved and the changes should not be applied at all. +This closes the whole change request. Use this when the conflict should not be resolved and the changes should not be applied at all. ## Current limitations diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 9ed4bfd0..0d435d61 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -17,7 +17,7 @@ const features = [ { url: 'organization', title: 'Organization & Roles' }, { url: 'targeting/targeting-overview', title: 'Targeting' }, { url: 'advanced/predefined-variations', title: 'Predefined Variations vs Free‑Form Values' }, - { url: 'change-requests', title: 'Change Requests & Scheduled Changes (Beta)' }, + { url: 'change-requests', title: 'Approval flow & Scheduled Changes (Beta)' }, ], }, { From b5ebfe8a7107db9b7233863c16502496bc2afc4c Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:25:42 +0200 Subject: [PATCH 12/20] rewording --- website/docs/change-requests.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 0cad7db2..f46eabd8 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -5,10 +5,10 @@ description: Propose, schedule, and review feature flag changes with the ConfigC --- :::info -**Beta Feature**: Approval flow and scheduled changes are in closed beta. You can join the beta by contacting support at configcat.com/support. We are collecting feedback from real-world use to improve the experience. +**Beta Feature**: Approval flow & Scheduled Changes is in closed beta. You can join the beta by writing to our support at configcat.com/support. We are collecting feedback from real-world use to improve the experience. ::: -A change request is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. +A _Change Request_ is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. You can propose a change for later manual publishing, or schedule it to be applied automatically at a specific time. This supports the four-eyes principle, because another person can review and approve the change before it reaches production. @@ -26,7 +26,7 @@ Feature flag changes in ConfigCat can be: - **Proposed**: Saved as a change request for later manual publishing. - **Scheduled**: Saved as a change request that ConfigCat applies automatically at a selected date and time. -If an environment is configured as approval-required, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes. A scheduled change request is only applied on schedule if it has been approved. +If an environment is configured as _approval-required_, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled change request is only applied on schedule if it has been approved. ## Permissions @@ -38,7 +38,7 @@ Only members with **Read/Write** permission for feature management in the enviro The **Approval flow** product preference controls which environments require approval. -You can enable it for the whole product or for each environment. +You can enable it for the entire product, or per environment. When an environment is approval-required, all feature flag changes must go through a change request. The only exception is the **Can bypass approval** permission, described below. @@ -137,7 +137,7 @@ This option starts from your proposed values and then lets you apply the changes ### Remove feature flag from change request -This removes that feature flag from the change request and discards its changes. This option is only available when the change request contains more than one feature flag. +This removes the feature flag from the change request and discards its changes. This option is only available when the change request contains more than one feature flag. ### Close change request From b02daa3a4d4b3d14b855930d9ceef3fb580ec28d Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:32:12 +0200 Subject: [PATCH 13/20] prg --- website/docs/change-requests.mdx | 88 +++++++++++++++++--------------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index f46eabd8..9f125561 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -1,11 +1,11 @@ --- id: change-requests title: Approval Flow & Scheduled Changes (Beta) -description: Propose, schedule, and review feature flag changes with the ConfigCat change requests. +description: Propose, schedule, and review feature flag changes with the ConfigCat Change Requests. --- :::info -**Beta Feature**: Approval flow & Scheduled Changes is in closed beta. You can join the beta by writing to our support at configcat.com/support. We are collecting feedback from real-world use to improve the experience. +**Beta Feature**: Approval Flow and Scheduled Changes are in closed beta. You can join the beta by contacting [support](https://configcat.com/support). We are collecting feedback from real-world use to improve the experience. ::: A _Change Request_ is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. @@ -23,54 +23,54 @@ Typical use cases: Feature flag changes in ConfigCat can be: - **Published immediately**: The classic way. The change takes effect right away. -- **Proposed**: Saved as a change request for later manual publishing. -- **Scheduled**: Saved as a change request that ConfigCat applies automatically at a selected date and time. +- **Proposed**: Saved as a Change Request for later manual publishing. +- **Scheduled**: Saved as a Change Request that ConfigCat applies automatically at a selected date and time. -If an environment is configured as _approval-required_, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled change request is only applied on schedule if it has been approved. +If an environment is configured as _approval-required_, changes cannot be applied immediately. A Change Request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled Change Request is only applied on schedule if it has been approved. ## Permissions -### Who can create change requests? +### Who can create Change Requests? Only members with **Read/Write** permission for feature management in the environment can propose or schedule changes. -### Approval flow product preference +### Approval Flow Product preference -The **Approval flow** product preference controls which environments require approval. +The **Approval Flow** Product preference controls which environments require approval. -You can enable it for the entire product, or per environment. +You can enable it for the entire product or per environment. You can manage it in the [Product preferences page](https://app.configcat.com/product/preferences). -When an environment is approval-required, all feature flag changes must go through a change request. The only exception is the **Can bypass approval** permission, described below. +When an environment is approval-required, all feature flag changes must go through a Change Request. The only exception is the **Can bypass approval** permission, described below. -### Change request approvals permission +### Change Request approvals permission -Permission groups include a **Change request approvals** permission with these values: +Permission groups include a **Change Request approvals** permission with these values: -- **Cannot approve**: The member cannot approve any change request. -- **Can approve others**: The member can approve change requests opened by other members. -- **Can bypass approval**: The member can approve change requests opened by other members, or apply changes directly without going through the approval flow. +- **Cannot approve**: The member cannot approve any Change Request. +- **Can approve others**: The member can approve Change Requests opened by other members. +- **Can bypass approval**: The member can approve Change Requests opened by other members, or apply changes directly without going through the approval flow. This permission can be set product-wide or overridden per environment. In approval-required environments: -- Members with **Read/Write** can create change requests and propose or schedule changes. -- Members with at least **Can approve others** can approve change requests. -- Members with **Read/Write** can apply an approved change request. -- Members with **Can bypass approval** can approve change requests or apply changes directly, skipping the approval step. -- Members with at least **Can approve others** can close any change request. +- Members with **Read/Write** can create Change Requests and propose or schedule changes. +- Members with at least **Can approve others** can approve Change Requests. +- Members with **Read/Write** can apply an approved Change Request. +- Members with **Can bypass approval** can approve Change Requests or apply changes directly, skipping the approval step. +- Members with at least **Can approve others** can close any Change Request. :::info **Can bypass approval** is meant for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in. It is never automatic. -For scheduled change requests, a member with **Can bypass approval** can choose to apply a scheduled change request on its set date without prior approval. This opt-in must be set for each change request. +For scheduled Change Requests, a member with **Can bypass approval** can choose to apply a scheduled Change Request on its set date without prior approval. This opt-in must be set for each Change Request. ::: -## Lifecycle of a change request +## Lifecycle of a Change Request ### Ownership and editing -Only the owner can edit a change request. Other members can: +Only the owner can edit a Change Request. Other members can: - comment on the request - approve it if they have the right permission @@ -78,44 +78,44 @@ Only the owner can edit a change request. Other members can: ### Comments, notifications, and activity -Each change request supports comments for team discussion. Email notifications are sent for important events, such as approvals, comments, and status changes. The activity log records everything that happened on the request. +Each Change Request supports comments for team discussion. Email notifications are sent for important events, such as approvals, comments, and status changes. The activity log records everything that happened on the request. ### Re-approval after edits -If the owner edits a change request, for example by changing feature flag values or the schedule, all existing approvals are removed. The request must be reviewed and approved again before it can be applied. +If the owner edits a Change Request, for example by changing feature flag values or the schedule, all existing approvals are removed. The request must be reviewed and approved again before it can be applied. ## Statuses -- **Open**: The change request has been created and is waiting to be applied. +- **Open**: The Change Request has been created and is waiting to be applied. - **Applied**: The changes have been published. -- **Closed**: The change request was closed without being applied. Closed change requests cannot be reopened. +- **Closed**: The Change Request was closed without being applied. Closed Change Requests cannot be reopened. ### Scheduled request fallback -If a scheduled change request cannot be applied at the planned time, for example because it was never approved, the schedule is removed and the request becomes a regular open change request. You can then fix the issue and apply it manually or schedule it again. +If a scheduled Change Request cannot be applied at the planned time, for example because it was never approved, the schedule is removed and the request becomes a regular open Change Request. You can then fix the issue and apply it manually or schedule it again. ### Needs approval -A change request shows **Needs approval** when it is in an approval-required environment and has not yet been approved. +A Change Request shows **Needs approval** when it is in an approval-required environment and has not yet been approved. ### Needs attention -A change request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can continue. +A Change Request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can continue. Possible causes: -- **Conflicting changes**: Changes for the same feature flags were published after the change request was opened. See [Conflict handling](#conflict-handling). -- **Owner is unavailable**: The owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the change request. -- **Missing mandatory notes**: Mandatory notes were enabled on the environment after the change request was created, and the change request does not have notes. -- **Circular dependency**: A change was published after the change request was opened, and applying the request now would create a circular dependency through prerequisite flags. +- **Conflicting changes**: Changes for the same feature flags were published after the Change Request was opened. See [Conflict handling](#conflict-handling). +- **Owner is unavailable**: The owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the Change Request. +- **Missing mandatory notes**: Mandatory notes were enabled on the environment after the Change Request was created, and the Change Request does not have notes. +- **Circular dependency**: A change was published after the Change Request was opened, and applying the request now would create a circular dependency through prerequisite flags. ## Conflict handling -When you open a change request, ConfigCat notifies you if another open change request already includes the same feature flags. +When you open a Change Request, ConfigCat notifies you if another open Change Request already includes the same feature flags. -This matters because if two change requests modify the same flag, the one applied first will mark the other as invalid. An invalid change request cannot be applied until its conflicts are resolved. +This matters because if two Change Requests modify the same flag, the one applied first will mark the other as invalid. An invalid Change Request cannot be applied until its conflicts are resolved. -The conflict resolver shows the changes your change request proposes and the changes that were published after you opened it. +The conflict resolver shows the changes your Change Request proposes and the changes that were published after you opened it. You can resolve conflicts in one of these ways: @@ -135,17 +135,21 @@ This option starts from the currently published values and then lets you re-appl This option starts from your proposed values and then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal. -### Remove feature flag from change request +### Remove feature flag from Change Request -This removes the feature flag from the change request and discards its changes. This option is only available when the change request contains more than one feature flag. +This removes the feature flag from the Change Request and discards its changes. This option is only available when the Change Request contains more than one feature flag. -### Close change request +### Close Change Request -This closes the whole change request. Use this when the conflict should not be resolved and the changes should not be applied at all. +This closes the whole Change Request. Use this when the conflict should not be resolved and the changes should not be applied at all. ## Current limitations -The approval flow currently applies to feature flag value changes only. The following actions do not require a change request or approval: +The approval flow currently applies to feature flag value changes only. The following actions do not require a Change Request or approval: - Creating or deleting a feature flag. - Changes to segments. + +### Removal restrictions + +Feature flags cannot be removed if they are referenced by a Change Request, including as prerequisites. Predefined variations cannot be removed if they are referenced by a Change Request. Segments cannot be removed if they are referenced by a Change Request. From 7abbe47599d978c2fcc2cfe8b1d483689c667fb4 Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:34:10 +0200 Subject: [PATCH 14/20] prg --- website/docs/change-requests.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 9f125561..d45c55c9 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -75,6 +75,7 @@ Only the owner can edit a Change Request. Other members can: - comment on the request - approve it if they have the right permission - close it if they have at least **Can approve others** +- apply it if they have **Read/Write** permission and the request is approved or doesn't require approval. ### Comments, notifications, and activity From e416326c1284fba2eae8e26975c83fe26371126a Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:35:49 +0200 Subject: [PATCH 15/20] prg --- website/docs/change-requests.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index d45c55c9..ce123452 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -91,10 +91,6 @@ If the owner edits a Change Request, for example by changing feature flag values - **Applied**: The changes have been published. - **Closed**: The Change Request was closed without being applied. Closed Change Requests cannot be reopened. -### Scheduled request fallback - -If a scheduled Change Request cannot be applied at the planned time, for example because it was never approved, the schedule is removed and the request becomes a regular open Change Request. You can then fix the issue and apply it manually or schedule it again. - ### Needs approval A Change Request shows **Needs approval** when it is in an approval-required environment and has not yet been approved. @@ -110,6 +106,10 @@ Possible causes: - **Missing mandatory notes**: Mandatory notes were enabled on the environment after the Change Request was created, and the Change Request does not have notes. - **Circular dependency**: A change was published after the Change Request was opened, and applying the request now would create a circular dependency through prerequisite flags. +#### Scheduled request fallback + +If a scheduled Change Request cannot be applied at the planned time, for example because it was never approved, the schedule is removed and the request becomes a regular open Change Request. You can then fix the issue and apply it manually or schedule it again. + ## Conflict handling When you open a Change Request, ConfigCat notifies you if another open Change Request already includes the same feature flags. @@ -153,4 +153,6 @@ The approval flow currently applies to feature flag value changes only. The foll ### Removal restrictions -Feature flags cannot be removed if they are referenced by a Change Request, including as prerequisites. Predefined variations cannot be removed if they are referenced by a Change Request. Segments cannot be removed if they are referenced by a Change Request. +- Feature flags cannot be removed if they are referenced by a Change Request, including as prerequisites. +- Predefined variations cannot be removed if they are referenced by a Change Request. +- Segments cannot be removed if they are referenced by a Change Request. From 34a81032e282d43455ff14be7de0ac66571e1840 Mon Sep 17 00:00:00 2001 From: Lajos Date: Tue, 7 Jul 2026 10:37:15 +0200 Subject: [PATCH 16/20] restrictions --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index ce123452..cc8d5d98 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -151,7 +151,7 @@ The approval flow currently applies to feature flag value changes only. The foll - Creating or deleting a feature flag. - Changes to segments. -### Removal restrictions +## Restrictions - Feature flags cannot be removed if they are referenced by a Change Request, including as prerequisites. - Predefined variations cannot be removed if they are referenced by a Change Request. From d1392ed436655772cc2a0a4643aa881ef31f999a Mon Sep 17 00:00:00 2001 From: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> Date: Wed, 8 Jul 2026 12:44:41 +0200 Subject: [PATCH 17/20] Apply suggestions from code review Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> --- website/docs/change-requests.mdx | 131 ++++++++++++++++--------------- 1 file changed, 67 insertions(+), 64 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index cc8d5d98..e8c26bad 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -1,158 +1,161 @@ --- id: change-requests title: Approval Flow & Scheduled Changes (Beta) -description: Propose, schedule, and review feature flag changes with the ConfigCat Change Requests. +description: Propose, schedule, and review feature flag changes using change requests. --- :::info **Beta Feature**: Approval Flow and Scheduled Changes are in closed beta. You can join the beta by contacting [support](https://configcat.com/support). We are collecting feedback from real-world use to improve the experience. ::: -A _Change Request_ is a set of feature flag changes that you prepare in the Dashboard without publishing them right away. -You can propose a change for later manual publishing, or schedule it to be applied automatically at a specific time. +A _change request_ is a set of feature flag changes that you prepare on ConfigCat Dashboard without publishing them right away. +You can propose changes for later manual publishing, or schedule it to be applied automatically at a specific time. This supports the four-eyes principle, because another person can review and approve the change before it reaches production. Typical use cases: -- **Scheduled release**: You want a feature turned on next Monday at 9 AM without being at your desk. -- **Approval before go-live**: You work in a regulated environment where a colleague must review every change before it reaches production. +- **Approval before publishing**: You work in a regulated environment where a colleague must review every change before it reaches production. - **Draft and collaborate**: You want to prepare changes, collect feedback in comments, and only publish when the team agrees. +- **Scheduled release**: You want a feature turned on next Monday at 9 AM without being at your desk. ## How does it work? Feature flag changes in ConfigCat can be: - **Published immediately**: The classic way. The change takes effect right away. -- **Proposed**: Saved as a Change Request for later manual publishing. -- **Scheduled**: Saved as a Change Request that ConfigCat applies automatically at a selected date and time. +- **Proposed**: Saved as a change request for later manual publishing. +- **Scheduled**: Saved as a change request that ConfigCat applies automatically at a selected date and time. + +If an environment is configured as _approval-required_, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. -If an environment is configured as _approval-required_, changes cannot be applied immediately. A Change Request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled Change Request is only applied on schedule if it has been approved. +This also applies to scheduled changes: a scheduled change request is only applied on schedule if it has been approved. ## Permissions -### Who can create Change Requests? +### Who can create change requests? -Only members with **Read/Write** permission for feature management in the environment can propose or schedule changes. +Only members who have **Read/Write** permission for feature management in the target environment may propose or schedule changes. -### Approval Flow Product preference +### How to require approval for environments? -The **Approval Flow** Product preference controls which environments require approval. +The **Approval Flow** product preferences control which environments require approval. -You can enable it for the entire product or per environment. You can manage it in the [Product preferences page](https://app.configcat.com/product/preferences). +You can enable it for the entire product or for specific environments. You can manage it on the [Product Preferences](https://app.configcat.com/product/preferences) page. -When an environment is approval-required, all feature flag changes must go through a Change Request. The only exception is the **Can bypass approval** permission, described below. +When an environment is approval-required, feature flag changes must first be proposed as a change request and then go through the approval flow. This process can be skipped only by members with **Can bypass approval** permission, described below. -### Change Request approvals permission +### How to manage permissions for approval flow? -Permission groups include a **Change Request approvals** permission with these values: +Permission groups include a **Change request approvals** permission, which can be set to one of the following values: -- **Cannot approve**: The member cannot approve any Change Request. -- **Can approve others**: The member can approve Change Requests opened by other members. -- **Can bypass approval**: The member can approve Change Requests opened by other members, or apply changes directly without going through the approval flow. +- **Cannot approve**: The member cannot approve change requests. +- **Can approve others**: The member can approve change requests opened by other members. +- **Can bypass approval**: The member can approve change requests opened by other members, or apply changes directly without going through the approval flow. -This permission can be set product-wide or overridden per environment. +This permission can be set product-wide or specified per environment. In approval-required environments: -- Members with **Read/Write** can create Change Requests and propose or schedule changes. -- Members with at least **Can approve others** can approve Change Requests. -- Members with **Read/Write** can apply an approved Change Request. -- Members with **Can bypass approval** can approve Change Requests or apply changes directly, skipping the approval step. -- Members with at least **Can approve others** can close any Change Request. +- Members with **Read/Write** permission can create change requests to propose or schedule changes. +- Members with **Can approve others** permission (or above) can approve change requests. +- Members with **Read/Write** permission can apply an approved change request. +- Members with **Can bypass approval** permission can approve change requests or apply changes directly, skipping the approval step. +- Members with **Can approve others** permission (or above) can close any change request. :::info -**Can bypass approval** is meant for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in. It is never automatic. +The **Can bypass approval** permission is intended for emergency situations. By default, both proposed and scheduled changes are expected to go through the approval flow. Bypassing approval always requires an explicit action by the user. It is never automatic. -For scheduled Change Requests, a member with **Can bypass approval** can choose to apply a scheduled Change Request on its set date without prior approval. This opt-in must be set for each Change Request. +For scheduled change requests, a member with **Can bypass approval** permission can choose to apply the change request on schedule without prior approval. However, they must opt in to this behavior per change request. ::: -## Lifecycle of a Change Request +## Lifecycle of a change request ### Ownership and editing -Only the owner can edit a Change Request. Other members can: +Only the owner can edit a change request. Other members can: -- comment on the request -- approve it if they have the right permission -- close it if they have at least **Can approve others** -- apply it if they have **Read/Write** permission and the request is approved or doesn't require approval. +- comment on the change request, +- approve it if they have the appropriate permission, +- close it if they have **Can approve others** permission, +- apply it if they have **Read/Write** permission and the change request is approved or doesn't require approval. ### Comments, notifications, and activity -Each Change Request supports comments for team discussion. Email notifications are sent for important events, such as approvals, comments, and status changes. The activity log records everything that happened on the request. +Change requests allow comments for team discussion. Email notifications are sent on important events, such as approvals, comments, and status changes. The activity log records everything that happens on the change request. ### Re-approval after edits -If the owner edits a Change Request, for example by changing feature flag values or the schedule, all existing approvals are removed. The request must be reviewed and approved again before it can be applied. +If the owner edits a change request, for example, by updating the proposed changes or schedule, the existing approval is removed. The request must be reviewed and approved again before it can be applied. ## Statuses -- **Open**: The Change Request has been created and is waiting to be applied. -- **Applied**: The changes have been published. -- **Closed**: The Change Request was closed without being applied. Closed Change Requests cannot be reopened. +- **Open**: The change request has been created and is waiting to be applied. +- **Applied**: The change request has been applied, meaning that the proposed changes have been published. +- **Closed**: The change request has been closed without being applied. Closed change requests cannot be reopened. ### Needs approval -A Change Request shows **Needs approval** when it is in an approval-required environment and has not yet been approved. +A change request is labeled as **Needs approval** when it is in an approval-required environment and has not yet been approved. ### Needs attention -A Change Request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can continue. +A change request is labeled as **Needs attention** when there is a blocking issue that prevents it from being applied, either manually or on schedule. The issue must be resolved before the change request can move forward. Possible causes: -- **Conflicting changes**: Changes for the same feature flags were published after the Change Request was opened. See [Conflict handling](#conflict-handling). -- **Owner is unavailable**: The owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the Change Request. -- **Missing mandatory notes**: Mandatory notes were enabled on the environment after the Change Request was created, and the Change Request does not have notes. -- **Circular dependency**: A change was published after the Change Request was opened, and applying the request now would create a circular dependency through prerequisite flags. +- **Conflicting changes**: Changes to the included feature flags were published concurrently after the change request was opened. See [Conflict handling](#conflict-handling). +- **Owner is unavailable**: The change request owner left the organization or lost **Read/Write** permission in the target environment. Another eligible member must claim the change request. +- **Missing mandatory notes**: Notes became mandatory in the target environment after the change request was created, but no notes were provided. +- **Circular dependency**: Changes to the included feature flags were published concurrently after the change request was opened, and applying the change request now would create a circular dependency through prerequisite flags. -#### Scheduled request fallback +#### Failed to apply on schedule -If a scheduled Change Request cannot be applied at the planned time, for example because it was never approved, the schedule is removed and the request becomes a regular open Change Request. You can then fix the issue and apply it manually or schedule it again. +If a scheduled change request cannot be applied at the planned time (for example, because it was never approved), scheduling is disabled and the change request becomes a regular open change request. You can then resolve the issue and apply it manually or schedule it again. ## Conflict handling -When you open a Change Request, ConfigCat notifies you if another open Change Request already includes the same feature flags. +When you create a change request, ConfigCat warns you if another open change request in the target environment already includes the same feature flags. -This matters because if two Change Requests modify the same flag, the one applied first will mark the other as invalid. An invalid Change Request cannot be applied until its conflicts are resolved. +This is important because when two change requests modify the same feature flag, applying one will mark the other as invalid. Such a change request cannot be applied until its conflicts are resolved. -The conflict resolver shows the changes your Change Request proposes and the changes that were published after you opened it. +The **Resolve conflicts** dialog shows the changes your change request proposes and the changes that were published concurrently after you created it (or after you last resolved its conflicts). You can resolve conflicts in one of these ways: -### Auto merge +### Auto-merge -This option automatically merges your proposed changes with the currently published state. It is only available when the system can merge the changes safely. +This option automatically merges your proposed version with the currently published version. It is only available when the system can merge the changes safely. :::tip -Always review the merged result carefully before applying it to make sure it shows the correct values. +Always review the merged result before applying it to ensure it produces the intended behavior. ::: -### Accept theirs and re-apply your changes +### Accept their version and re-apply your changes -This option starts from the currently published values and then lets you re-apply your intended changes on top. Use this when you want your changes applied to the current state of the flag. This is the recommended option when Auto merge is not available. +This option allows you to resolve conflicts starting from the current published version. Choose this if it is easier to re-apply your intended changes. This is the recommended option when Auto-merge is not available. -### Accept yours and re-apply the published changes +### Accept your version and re-apply the changes published since -This option starts from your proposed values and then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal. +This option allows you to resolve conflicts starting from your proposed version. Choose this if it is easier to re-apply the concurrently published changes. -### Remove feature flag from Change Request +### Remove feature flag from change request -This removes the feature flag from the Change Request and discards its changes. This option is only available when the Change Request contains more than one feature flag. +This option removes the feature flag from the change request and discards its changes. This option is only available when the change request includes more than one feature flag. -### Close Change Request +### Close change request -This closes the whole Change Request. Use this when the conflict should not be resolved and the changes should not be applied at all. +This option closes the entire change request. Choose this when the conflict cannot or should not be resolved at all. ## Current limitations -The approval flow currently applies to feature flag value changes only. The following actions do not require a Change Request or approval: +The approval flow currently applies to feature flag changes only. The following actions do not require a change request or approval: - Creating or deleting a feature flag. +- Changes to predefined variations. - Changes to segments. ## Restrictions -- Feature flags cannot be removed if they are referenced by a Change Request, including as prerequisites. -- Predefined variations cannot be removed if they are referenced by a Change Request. -- Segments cannot be removed if they are referenced by a Change Request. +- Feature flags cannot be deleted if they are referenced by a change request (even if referenced indirectly, as prerequisites). +- Predefined variations cannot be removed if the feature flag is referenced by a change request. +- Segments cannot be removed if they are used in a feature flag referenced by a change request. From 3c9afe83d7f0a6457fa2a08314bd7fb8ebc80857 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Wed, 8 Jul 2026 12:51:51 +0200 Subject: [PATCH 18/20] links and v2 notice --- website/docs/change-requests.mdx | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index e8c26bad..cbe02891 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -34,7 +34,7 @@ This also applies to scheduled changes: a scheduled change request is only appli ### Who can create change requests? -Only members who have **Read/Write** permission for feature management in the target environment may propose or schedule changes. +Only members who have **Read/Write** permission for feature management in the target environment may propose or schedule changes. ### How to require approval for environments? @@ -42,11 +42,11 @@ The **Approval Flow** product preferences control which environments require app You can enable it for the entire product or for specific environments. You can manage it on the [Product Preferences](https://app.configcat.com/product/preferences) page. -When an environment is approval-required, feature flag changes must first be proposed as a change request and then go through the approval flow. This process can be skipped only by members with **Can bypass approval** permission, described below. +When an environment is approval-required, feature flag changes must first be proposed as a change request and then go through the approval flow. This process can be skipped only by members with **Can bypass approval** permission, described below. ### How to manage permissions for approval flow? -Permission groups include a **Change request approvals** permission, which can be set to one of the following values: +Permission groups include a **Change request approvals** permission, which can be set to one of the following values: - **Cannot approve**: The member cannot approve change requests. - **Can approve others**: The member can approve change requests opened by other members. @@ -65,7 +65,7 @@ In approval-required environments: :::info The **Can bypass approval** permission is intended for emergency situations. By default, both proposed and scheduled changes are expected to go through the approval flow. Bypassing approval always requires an explicit action by the user. It is never automatic. -For scheduled change requests, a member with **Can bypass approval** permission can choose to apply the change request on schedule without prior approval. However, they must opt in to this behavior per change request. +For scheduled change requests, a member with **Can bypass approval** permission can choose to apply the change request on schedule without prior approval. However, they must opt in to this behavior per change request. ::: ## Lifecycle of a change request @@ -99,14 +99,14 @@ A change request is labeled as **Needs approval** when it is in an approval-requ ### Needs attention -A change request is labeled as **Needs attention** when there is a blocking issue that prevents it from being applied, either manually or on schedule. The issue must be resolved before the change request can move forward. +A change request is labeled as **Needs attention** when there is a blocking issue that prevents it from being applied, either manually or on schedule. The issue must be resolved before the change request can move forward. Possible causes: -- **Conflicting changes**: Changes to the included feature flags were published concurrently after the change request was opened. See [Conflict handling](#conflict-handling). -- **Owner is unavailable**: The change request owner left the organization or lost **Read/Write** permission in the target environment. Another eligible member must claim the change request. -- **Missing mandatory notes**: Notes became mandatory in the target environment after the change request was created, but no notes were provided. -- **Circular dependency**: Changes to the included feature flags were published concurrently after the change request was opened, and applying the change request now would create a circular dependency through prerequisite flags. +- **Conflicting changes**: Changes to the included feature flags were published concurrently after the change request was opened. See [Conflict handling](#conflict-handling). +- **Owner is unavailable**: The change request owner left the organization or lost **Read/Write** permission in the target environment. Another eligible member must claim the change request. +- **Missing mandatory notes**: Notes became mandatory in the target environment after the change request was created, but no notes were provided. +- **Circular dependency**: Changes to the included feature flags were published concurrently after the change request was opened, and applying the change request now would create a circular dependency through [prerequisite flags](../targeting/targeting-rule/flag-condition/). #### Failed to apply on schedule @@ -116,7 +116,7 @@ If a scheduled change request cannot be applied at the planned time (for example When you create a change request, ConfigCat warns you if another open change request in the target environment already includes the same feature flags. -This is important because when two change requests modify the same feature flag, applying one will mark the other as invalid. Such a change request cannot be applied until its conflicts are resolved. +This is important because when two change requests modify the same feature flag, applying one will mark the other as invalid. Such a change request cannot be applied until its conflicts are resolved. The **Resolve conflicts** dialog shows the changes your change request proposes and the changes that were published concurrently after you created it (or after you last resolved its conflicts). @@ -136,7 +136,7 @@ This option allows you to resolve conflicts starting from the current published ### Accept your version and re-apply the changes published since -This option allows you to resolve conflicts starting from your proposed version. Choose this if it is easier to re-apply the concurrently published changes. +This option allows you to resolve conflicts starting from your proposed version. Choose this if it is easier to re-apply the concurrently published changes. ### Remove feature flag from change request @@ -144,12 +144,13 @@ This option removes the feature flag from the change request and discards its ch ### Close change request -This option closes the entire change request. Choose this when the conflict cannot or should not be resolved at all. +This option closes the entire change request. Choose this when the conflict cannot or should not be resolved at all. -## Current limitations +## Limitations The approval flow currently applies to feature flag changes only. The following actions do not require a change request or approval: +- The features are only available for V2 configs. See the [Config V2 Migration Guide](../advanced/config-v2-migration-guide). - Creating or deleting a feature flag. - Changes to predefined variations. - Changes to segments. From 71facfd64bc2da024712afca8d791a948a18b60d Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Wed, 8 Jul 2026 17:58:01 +0200 Subject: [PATCH 19/20] permission text --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index cbe02891..34253b04 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -59,7 +59,7 @@ In approval-required environments: - Members with **Read/Write** permission can create change requests to propose or schedule changes. - Members with **Can approve others** permission (or above) can approve change requests. - Members with **Read/Write** permission can apply an approved change request. -- Members with **Can bypass approval** permission can approve change requests or apply changes directly, skipping the approval step. +- Members with **Can bypass approval** permission can approve change requests or apply changes directly if they also have "Read/Write" permission, effectively bypassing the approval flow. - Members with **Can approve others** permission (or above) can close any change request. :::info From 529b27c70ae740cfd4cc691b11191efa061b7175 Mon Sep 17 00:00:00 2001 From: Lajos Szoke Date: Wed, 8 Jul 2026 18:18:49 +0200 Subject: [PATCH 20/20] bypass --- website/docs/change-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/change-requests.mdx b/website/docs/change-requests.mdx index 34253b04..1b71e853 100644 --- a/website/docs/change-requests.mdx +++ b/website/docs/change-requests.mdx @@ -59,7 +59,7 @@ In approval-required environments: - Members with **Read/Write** permission can create change requests to propose or schedule changes. - Members with **Can approve others** permission (or above) can approve change requests. - Members with **Read/Write** permission can apply an approved change request. -- Members with **Can bypass approval** permission can approve change requests or apply changes directly if they also have "Read/Write" permission, effectively bypassing the approval flow. +- Anyone with the **Can bypass approval** permission can approve any change request. If they also have **Read/Write** permission, they can even apply changes directly, effectively skipping the approval flow. - Members with **Can approve others** permission (or above) can close any change request. :::info