Skip to content

Update index.md #3048

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HarrietAlexander wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update index.md #3048

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b200e7e
Update index.md
HarrietAlexander Mar 4, 2026
3dc54b0
Typo and lint errors
steve-fenton-octopus Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 39 additions & 39 deletions src/pages/docs/feature-toggles/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,56 @@
---
layout: src/layouts/Default.astro
pubDate: 2025-05-21
modDate: 2025-05-21
modDate: 2026-03-04
title: Feature Toggles
Copy link
Contributor

@steve-fenton-octopus steve-fenton-octopus Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As all these titles are the same, we can just use the title.

navTitle: Feature Toggles
navSection: Feature Toggles
description: Octopus Feature Toggles allow progressive delivery of changes and instant rollback
navOrder: 95
---

Octopus Feature Toggles support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users.
Octopus Feature Toggles let you turn features on or off in real time, without redeployment. This enables you to progressively release changes to a subset of your users.

:::div{.hint}
Octopus Feature Toggles are currently in Alpha, available to a small set of customers.
Octopus Feature Toggles are currently in Preview, available to a limited group 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.
If you are interested in this feature please register your interest on the [roadmap card](https://roadmap.octopus.com/c/121-feature-toggles). We will keep you updated.
Copy link
Contributor

@steve-fenton-octopus steve-fenton-octopus Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We prefer the informal "we'll" usually.

Suggested change
If you are interested in this feature please register your interest on the [roadmap card](https://roadmap.octopus.com/c/121-feature-toggles). We will keep you updated.
If you are interested in this feature please register your interest on the [roadmap card](https://roadmap.octopus.com/c/121-feature-toggles). We'll keep you updated.

:::

## Usage
## Usage

### Create a Feature Toggle
### Create a Feature Toggle

Feature Toggles are located within Octopus Projects:
You can find Feature Toggles within Octopus Projects:
**Project ➜ Feature Toggles**

Create a new Toggle and give it name.
Create a new Toggle and name it

![New toggle name](/docs/img/feature-toggles/new-toggle-name.png)

### Configure OpenFeature in your client application {#configure-open-feature-client-app}

Octopus Feature Toggles 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.
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](#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 Toggle service which set of toggles to evaluate.
The Octopus OpenFeature Provider requires a client identifier when instantiated. This identifier is a [JWT](https://jwt.io/introduction) that specifies the Octopus Project, Environment, and Tenant (if applicable). It tells the Octopus Feature Toggle service which set of toggles to evaluate.

:::div{.hint}
The Octopus Feature Toggle client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Toggle UI (see below).
The Octopus Feature Toggle client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Toggle 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 deployed by Octopus, the recommended approach is to have Octopus inject the client identifier as during your deployment, for example, injecting it into a configuration file or environment variable. The client identifier is made available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier`.
Copy link
Contributor

@liamhughes liamhughes Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For applications deployed by Octopus, the recommended approach is to have Octopus inject the client identifier as during your deployment, for example, injecting it into a configuration file or environment variable. The client identifier is made available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier`.
For applications deployed by Octopus, the recommended approach is to have Octopus inject the client identifier during your 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.
For applications not deployed by Octopus, or those that cannot have the client identifier supplied during deployment, r cannot have the client identifier supplied during deployment, the client identifier can be obtained through the portal UI, as shown below.
Copy link
Contributor

@steve-fenton-octopus steve-fenton-octopus Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding a missing "o" on "or" and we probably only need the last "or".

Suggested change
For applications not deployed by Octopus, or those that cannot have the client identifier supplied during deployment, r cannot have the client identifier supplied during deployment, the client identifier can be obtained through the portal UI, as shown below.
For applications not deployed by Octopus, that cannot have the client identifier supplied during deployment, or cannot have the client identifier supplied during deployment, the client identifier can be obtained through 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:
For example, an ASP.NET application could have an `appsettings.json` file which contained the following:

```json
{
Expand All @@ -62,7 +60,7 @@ For example, an ASP.NET application could have an `appsettings.json` file which
}
```

This would be transformed during deployment by Octopus to contain the correct client identifier for the current Project and Environment.
During deployment, Octopus transforms this to contain the correct client identified for the current Project and Environment.
Copy link
Contributor

@steve-fenton-octopus steve-fenton-octopus Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be identified or identifier?

Suggested change
During deployment, Octopus transforms this to contain the correct client identified for the current Project and Environment.
During deployment, Octopus transforms this 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:

Expand Down Expand Up @@ -94,12 +92,13 @@ var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", fals

The second argument is the default value. Read more about [default values](#default-values) below.

### Rollout
To enable your toggle for an environment, add the environment to the Toggle.
### Rollout

To enable your toggle for an environment, add the environment to the Toggle.

![Add Environment button](/docs/img/feature-toggles/add-environment-button.png)

Select your environment, and whether you want the toggle on or off.
Select your environment, and choose whether to toggle it on or off.

![Add Environment dialog](/docs/img/feature-toggles/add-environment-dialog.png)

Expand All @@ -110,27 +109,28 @@ You can additionally target specific [Tenants](#tenants) or [User Segments](#seg
Below are the Octopus OpenFeature provider SDKs currently available:

### 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)

Configuring the providers is documented in the README files in the repositories.

## Segments {#segments}

Segments allow enabling a toggle for a subset of users.

Segments are key/value pairs, and are supplied by your applications via the [OpenFeature EvaluationContext](https://openfeature.dev/docs/reference/concepts/evaluation-context).
Segments allow enabling a toggle for a subset of users.

Segments are key/value pairs supplied by your applications via the [OpenFeature EvaluationContext](https://openfeature.dev/docs/reference/concepts/evaluation-context).

Common segment examples include:

- Specific users. e.g. `user-id/123456`
- Specific accounts. e.g. `account-id/123456`
- Specific accounts. e.g. `account-id/123456`
- License types. e.g. `license-type/free`
- Geographic regions. e.g. `region/eu`
- Geographic regions. e.g. `region/eu`
- Rollout rings. e.g. `ring/early-adopter`

The Evaluation Context can be supplied at different points in your application, for example:
Expand All @@ -139,7 +139,7 @@ The Evaluation Context can be supplied at different points in your application,
- During each web request
- At the evaluation site

The following example shows adding a key/value to the evaluation context in C#.
The following example shows how to add key/value pair to the evaluation context in C#.
Copy link
Contributor

@liamhughes liamhughes Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following example shows how to add key/value pair to the evaluation context in C#.
The following example shows how to add a key/value pair to the evaluation context in C#.


```cs
// The client would be injected by IoC in many cases
Expand All @@ -152,20 +152,20 @@ Segments can then be configured for Environments on the Feature Toggle in Octopu

![Add Segment](/docs/img/feature-toggles/segment-add.png)

A Toggle evaluation will match on segments if the evaluation context matches at least one segment for each key.
A Toggle evaluation will match on segments if the evaluation context matches at least one segment for each key.

Some examples:

|Segments | Evaluation Context | Result |
|-----------|--------------------|--------|
| `user-id/123456` | `user-id/123456` | `On` |
| `user-id/123456` | `user-id/789383` | `Off` |
| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/Asia` | `On` |
| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/US` | `Off` |
| Segments | Evaluation Context | Result |
| --------------------------------------------- | --------------------------------- | ------ |
| `user-id/123456` | `user-id/123456` | `On` |
| `user-id/123456` | `user-id/789383` | `Off` |
| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/Asia` | `On` |
| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/US` | `Off` |

## Tenants {#tenants}

If your Project uses [Tenants](/docs/tenants/), then Toggles may be enabled for subsets of your Tenants.
If your Project uses [Tenants](/docs/tenants/), then Toggles may be enabled for subsets of your Tenants.

The options for configuring a Feature Toggle for Tenants are:

Expand All @@ -174,22 +174,22 @@ The options for configuring a Feature Toggle for Tenants are:
- % of Tenants
- Specific Tenants Excluded

For example, the configuration shown below will result in the Toggle evaluating as `On` for 10% of Tenants, always including `Acme` and never including `Cyberdyne Systems`.
For example, the configuration shown below will result in the Toggle evaluating as `On` for 10% of Tenants, always including `Acme` and never including `Cyberdyne Systems`.

![Tenanted Rollout](/docs/img/feature-toggles/tenant-rollout.png)

## Default Values {#default-values}

Toggle default values are configured both on the Toggle in Octopus, and at the evaluation site in your client application. It's important to understand how these interact.
Toggle default values are configured both on the Toggle in Octopus, and at the evaluation site in your client application. It's important to understand how these interact.

The default value on the Toggle 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 Toggle 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`).
In the example below, the `Production` and `Staging` environments have values configured. The default value for the Toggle 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 Toggle service cannot be reached, for example if there are network issues or the service is unavailable.
The default value supplied in the client code (the `false` argument in the example below) will only be used if the Octopus Feature Toggle service cannot be reached, for example, due to network issues or unavailability.

```cs
var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false);
```
```