OctopusDeploy · dylanlerch · Jun 1, 2026
diff --git a/src/pages/docs/feature-flags/index.md b/src/pages/docs/feature-flags/index.md
@@ -0,0 +1,124 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2025-05-21
+modDate: 2026-06-02
+title: Feature Flags
+icon: fa-solid fa-toggle-on
+navTitle: Overview
+navSection: Feature Flags
+description: Octopus Feature Flags allow progressive delivery of changes and instant rollback 
+navOrder: 95
+---
+
+Octopus Feature Flags support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users.
+
+:::div{.hint}
+Octopus Feature Flags are currently in Alpha, available to a small set of customers.
+
+If you are interested in this feature please register your interest on the [roadmap card](https://roadmap.octopus.com/c/121-feature-toggles) and we'll keep you updated.
+:::
+
+## Usage
+
+### Create a Feature Flag
+
+Feature Flags are located within Octopus Projects:
+**Project ➜ Feature Flags**
+
+Create a new Flag and give it name.
+
+![New flag name](/docs/img/feature-toggles/new-toggle-name.png)
+
+### Configure OpenFeature in your client application {#configure-open-feature-client-app}
+
+Octopus Feature Flags rely on [OpenFeature](https://openfeature.dev/) as the client SDK.
+
+Follow the [OpenFeature guide for installing the SDK for your language](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=SDK) into your application.
+
+Configure OpenFeature to use the [Octopus Provider](/docs/feature-flags/providers).
+
+The Octopus OpenFeature Provider requires a client identifier when instantiated. This is a [JWT](https://jwt.io/introduction) which specifies the Octopus Project, Environment, and Tenant (if applicable). This tells the Octopus Feature Flag service which set of flags to evaluate.
+
+:::div{.hint}
+The Octopus Feature Flag client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Flag UI (see below).
+:::
+
+For applications deployed by Octopus, the recommended way is to have Octopus inject the client identifier as part of deployment, for example by injecting it into a configuration file or environment variable. The client identifier is made available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier`.
+
+For applications not deployed by Octopus, or cannot have the client identifier supplied during deployment for any reason, the client identifier can be obtained via the portal UI, as shown below.
+
+![Client identifier preview menu item](/docs/img/feature-toggles/client-identifier-preview-menu-item.png)
+
+![Client identifier preview UI](/docs/img/feature-toggles/client-identifier-preview.png)
+
+The previewed client identifier may then be copied into your application configuration.
+
+For example, an ASP.NET application could have an `appsettings.json` file which contained the following:
+
+```json
+{
+  "FeatureToggles": {
+    "ClientId": "#{Octopus.FeatureToggles.ClientIdentifier}"
+  }
+}
+```
+
+This would be transformed during deployment by Octopus to contain the correct client identifier for the current Project and Environment.
+
+This would then be used during application startup to configure the OpenFeature with the Octopus Provider, similar to:
+
+```cs
+// Retrieve client identifier from config 
+var builder = WebApplication.CreateBuilder(args);
+var octopusFeatureTogglesClientId = builder.Configuration["FeatureToggles:ClientId"] ?? "";
+
+// Instantiate the Octopus Provider
+var octopusProvider = new OctopusFeatureProvider(new OctopusFeatureConfiguration(octopusFeatureTogglesClientId));
+
+// Set Octopus as the OpenFeature provider
+await OpenFeature.Api.Instance.SetProviderAsync(octopusProvider);
+```
+
+### Evaluate a Flag
+
+The [Provider](/docs/feature-flags/providers) for each language documents how to evaluate flags.
+
+You will need the Flag slug in order to reference the flag in code. This can be found in the Octopus portal:
+
+![Feature Flag slug](/docs/img/feature-toggles/feature-toggle-slug.png)
+
+Below is an example of evaluating the flag with slug `dark-mode` in C#:
+
+```cs
+var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false);
+```
+
+The second argument is the default value. Read more about [default values](#default-values) below.
+
+### Rollout
+
+To enable your flag for an environment, add the environment to the Flag.
+
+![Add Environment button](/docs/img/feature-toggles/add-environment-button.png)
+
+Select your environment, and whether you want the flag on or off.
+
+![Add Environment dialog](/docs/img/feature-toggles/add-environment-dialog.png)
+
+You can additionally control rollout within an environment. See [Feature Flag targeting](/docs/feature-flags/targeting) for more information.
+
+## Default Values {#default-values}
+
+Flag default values are configured both on the Flag in Octopus, and at the evaluation site in your client application. It's important to understand how these interact.
+
+The default value on the Flag in Octopus will be returned if the environment being evaluated has not been configured with an explicit value.
+
+In the example below, the `Production` and `Staging` environments have values configured. The default value for the Flag is `Off`. If an evaluation is made by an application running in the `Development` environment, or any other environment not configured, it would receive the default value (`Off`).  
+
+![Default Values](/docs/img/feature-toggles/default-values.png)
+
+The default value supplied in client code (the `false` argument in the example below) will only be used if the Octopus Feature Flag service cannot be reached, for example if there are network issues or the service is unavailable.
+
+```cs
+var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false);
+```
diff --git a/src/pages/docs/feature-flags/providers.md b/src/pages/docs/feature-flags/providers.md
@@ -0,0 +1,22 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-04-20
+modDate: 2026-06-02
+title: OpenFeature Providers
+icon: fa-solid fa-code
+navTitle: OpenFeature Providers
+navSection: Feature Flags
+description: OpenFeature providers for Octopus Feature Flags
+navOrder: 97
+---
+
+These are the available Octopus OpenFeature provider SDKs. Getting started instructions for each of these providers is documented in the README files in the repositories.
+
+## Server SDKs
+
+- [.NET](https://github.com/OctopusDeploy/openfeature-provider-dotnet)
+- [Java](https://github.com/OctopusDeploy/openfeature-provider-java)
+
+## Web SDKs
+
+- [TypeScript/JavaScript](https://github.com/OctopusDeploy/openfeature-provider-ts-web)
diff --git a/src/pages/docs/feature-flags/targeting.md b/src/pages/docs/feature-flags/targeting.md
@@ -0,0 +1,125 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-04-20
+modDate: 2026-06-02
+title: Targeting
+subtitle: Configure rollout within an environment
+icon: fa-solid fa-bullseye
+navTitle: Targeting
+navSection: Feature Flags
+description: Targeting options for Octopus Feature Flags
+navOrder: 96
+---
+
+## Minimum version
+
+You can configure a feature flag to require a minimum version before being enabled in an environment. The flag will be enabled once that version (or any later version) is deployed to that environment.
+
+![Screenshot of feature flag environment drawer, minimum version section is expanded, minimum version input has value 12.1.0](/docs/img/feature-toggles/minimum-version.png)
+
+## Tenants {#tenants}
+
+If your project uses [Tenants](/docs/tenants/), you can configure a feature flag to be enabled for subsets of your tenants within an environment.
+
+There are many options for configuring a feature flag for tenants. These are all modeled in Octopus and do not require any custom configuration in application code.
+
+### Excluded tenants
+
+You can exclude tenants individually or exclude groups of tenants using tenant tags. Excluded tenants will always override any other rollout configuration, even if the rollout percentage is set to 100%.
+
+![Screenshot of feature flag environment drawer, excluded tenants section expanded, tenants to exclude multi-select has Acme Corporation and Contoso Ltd tenants selected, tenant tags to exclude multi-select has Tier/Enterprise tag selected](/docs/img/feature-toggles/excluded-tenants.png)
+
+Once a feature flag is configured with an excluded tenant tag, any changes to tenant tag assignments apply immediately to feature flags (no update to the feature flag configuration is required).
+
+### Included tenants
+
+You can enable feature flags for individual tenants. These tenants will always be included, even if the tenant rollout percentage is set to 0%.
+
+![Screenshot of feature flag environment drawer, included tenants section expanded, tenants to include multi-select has Acme Corporation selected, tenant rollout percentage and tenant tags to include in rollout inputs are empty](/docs/img/feature-toggles/included-tenants.png)
+
+### Tenant rollout
+
+Tenant rollout allows you to enable a flag for a pseudorandom percentage of all tenants.
+
+The included tenants are determined using a MurmurHash of the tenant ID and a flag-specific key. This guarantees deterministic evaluation for any given tenant and flag combination, while ensuring that a different set of tenants is included for each flag.
+
+![Screenshot of feature flag environment drawer, included tenants section expanded, tenants to include is empty, tenant rollout percentage is set to 50% and tenant tags to include in rollout multi-select has Tier/Free, Region/Australia, and Region/Europe selected](/docs/img/feature-toggles/tenant-rollout.png)
+
+You can further restrict the rollout using tenant tags. For example, if you specify `Region/Australia`, `Region/Europe`, and `Tier/Enterprise`, a 50% rollout will only apply to 50% of Enterprise tenants in either Australia or Europe. If you do not specify any tenant tags, a 50% rollout will apply to 50% of all tenants.
+
+As with excluded tenants, any changes to tenant tags apply immediately to feature flags.
+
+## Client rollout
+
+Client rollout allows you to enable a flag for a random percentage of your application users. The included users are determined using a MurmurHash of the [OpenFeature Targeting Key](https://openfeature.dev/docs/reference/concepts/evaluation-context#targeting-key) and a flag-specific key. This guarantees deterministic evaluation for any given user and flag combination.
+
+To use client rollout, you must configure a targeting key in your OpenFeature client. Refer to the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) documentation for your development language for details on how to set the targeting key. If you do not set a targeting key, the feature flag will not be enabled for any users unless the rollout is set to 100%.
+
+You should set the targeting key to a value that uniquely identifies your evaluation subject. For most applications, this will be a user identifier (such as a user ID), but you can use any identifier that suits your needs (for example, team, region, or server instance).
+
+:::div{.warning}
+Support for client rollout percentages was added in the following versions of the [provider libraries](/docs/feature-flags/providers):
+
+- [.NET: `2.1.0`](https://github.com/OctopusDeploy/openfeature-provider-dotnet/releases/tag/v2.1.0)
+- [Java: `0.3.0`](https://github.com/OctopusDeploy/openfeature-provider-java/releases/tag/0.3.0)
+- [TypeScript/JavaScript: `3.0.0`](https://github.com/OctopusDeploy/openfeature-provider-ts-web/releases/tag/v3.0.0)
+
+If you are not running the required minimum version of these libraries, the rollout percentage will be ignored (and handled as if the value was set to 100%).
+:::
+
+### Segments {#segments}
+
+Segments allow you to further refine the client rollout for a flag based on data that is not modeled in Octopus. Segments are key/value pairs, and are supplied by your application via the [OpenFeature evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).
+
+Like tenant targeting, segments are configured per-environment on the feature flag in Octopus.
+
+![Screenshot of feature flag environment drawer, client rollout section expanded, client rollout percentage is set to 50% with 3 segments region/eu, region/au, and ring/early-adopter](/docs/img/feature-toggles/segments.png)
+
+Refer to the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) documentation for your development language for more details on how to set these values.
+
+Common segment examples include:
+
+- Specific users (e.g. `user-id/123456`)
+- Specific accounts (e.g. `account-id/123456`)
+- License types (e.g. `license-type/free`)
+- Geographic regions (e.g. `region/eu`)
+- Rollout rings (e.g. `ring/early-adopter`)
+
+A feature flag evaluation will match on segments if the evaluation context matches at least one segment for each key. If you specify `ring/early-adopter`, `region/eu`, and `region/au`, the rollout will apply only to users in the early-adopter ring who are in either the EU or AU regions. If you do not specify any segments, the rollout will apply to all users.
+
+Some examples:
+
+| Segments                                       | Evaluation Context                | Result |
+|------------------------------------------------|-----------------------------------|--------|
+| `user-id/123456`                               | `user-id/123456`                  | `On`   |
+| `user-id/123456`                               | `user-id/789383`                  | `Off`  |
+| `ring/early-adopter`, `region/eu`, `region/au` | `ring/early-adopter`, `region/eu` | `On`   |
+| `ring/early-adopter`, `region/eu`, `region/au` | `ring/early-adopter`, `region/au` | `On`   |
+| `ring/early-adopter`, `region/eu`, `region/au` | `license-type/free`               | `Off`  |
+| `ring/early-adopter`, `region/eu`, `region/au` | `region/au`                       | `Off`  |
+
+## Rollout groups {#rollout-groups}
+
+By default, a percentage rollout on one feature flag will include a different set of tenants or clients than the same percentage rollout on another flag. This ensures the same tenants or clients are not always the first to receive every new feature.
+
+Rollout groups let you connect rollout evaluation between multiple feature flags so that the same tenants or clients are included in the rollout across those flags. This can be useful when you have related features that should roll out to the same audience.
+
+You can assign a rollout group to a feature flag from the feature flag page by selecting a group from the rollout group dropdown.
+
+![Screenshot of feature flag page showing rollout group selector expanded with new onboarding flow group selected](/docs/img/feature-toggles/rollout-group-selector.png)
+
+:::div{.warning}
+If you have a tenant or client rollout configured, adding, changing, or removing a rollout group on a feature flag will change which tenants or clients are included in that rollout.
+:::
+
+### Managing rollout groups
+
+You can manage rollout groups from the rollout groups page. To access this page, open the overflow menu on the feature flags list page and select **Manage Rollout Groups**.
+
+![Screenshot of feature flag list page with overflow menu expanded highlighting the manage rollout groups button](/docs/img/feature-toggles/manage-rollout-group-overflow.png)
+
+From the rollout groups page, you can add, rename, and delete rollout groups.
+
+![Screenshot of rollout group list page with a single rollout group named new onboarding flow, used by the live chat and AI recommendations feature flags, with the overflow menu expanded and showing edit and delete options](/docs/img/feature-toggles/rollout-group-page.png)
+
+You cannot delete a rollout group that is assigned to one or more feature flags. To delete a rollout group, first remove it from all feature flags that use it.