Feature Toggles

Octopus Feature Toggles support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users.

Usage

Create a Feature Toggle

Feature Toggles are located within Octopus Projects: Project ➜ Feature Toggles

Create a new Toggle and give it name.

Configure OpenFeature in your client application

Octopus Feature Toggles rely on OpenFeature as the client SDK.

Follow the OpenFeature guide for installing the SDK for your language into your application.

Configure OpenFeature to use the Octopus Provider.

The Octopus OpenFeature Provider requires a client identifier when instantiated. This is a JWT which specifies the Octopus Project, Environment, and Tenant (if applicable). This tells the Octopus Feature Toggle service which set of toggles to evaluate.

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.

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:

{
  "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:

// 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 Toggle

The Provider for each language documents how to evaluate toggles.

You will need the Toggle slug in order to reference the toggle in code. This can be found in the Octopus portal:

Below is an example of evaluating the toggle with slug dark-mode in C#:

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

The second argument is the default value. Read more about default values below.

Rollout

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

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

You can additionally target specific Tenants or User Segments.

Providers

Below are the Octopus OpenFeature provider SDKs currently available:

• .NET
• TypeScript/JavaScript

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

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.

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

The Evaluation Context can be supplied at different points in your application, for example:

• On start-up
• During each web request
• At the evaluation site

The following example shows adding a key/value to the evaluation context in C#.

// The client would be injected by IoC in many cases
var client = OpenFeature.Api.Instance.GetClient();
// The following is hard-coded, whereas a real-world use would set this dynamically
client.SetContext(EvaluationContext.Builder().Set("license-type", "free").Build());

Segments can then be configured for Environments on the Feature Toggle in Octopus.

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

Some examples:

Tenants

If your Project uses Tenants, then Toggles may be enabled for subsets of your Tenants.

The options for configuring a Feature Toggle for Tenants are:

• All Tenants
• Specific Tenants Included
• % 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.

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.

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

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.

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

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, May 21, 2025