Configuring a split release

3 minute read
Decreasing a live flag’s true percentage changes the flag consistency for some users. Refer to The implications of updating a live flag for more information.

CloudBees Feature Management boolean, string, and number flags can be configured to release the associated features to a specified percentage of users.

Split releases are designed to provide consistency for the user. The split is determined by a distributed algorithm that is similar to tossing a coin. When the page is revisited, the flag configuration persists, for a consistent user experience.

Percentage Rollouts

Configuring flags to display to a percentage of users.

Watch the video

Configuring a split percentage flag

You can configure boolean, string, and number flags as a split.

To create a split:

  1. Create a boolean, string, or number flag. Refer to Creating feature flags for more information.

    For string and number flags, you must enter variations during the creation process.
  2. Add any new conditions, and configure what is to be displayed to the percentage of users that the flag is true for. Refer to Configuring flags for release for more information.

  3. For then or else, select split.

    The split percentage is displayed, and defaults to a 50% split.

  4. (Optional) Adjust the percentage by selecting true or false and entering a number. You can also hover to display the arrow controls, and then select the up or down arrow. The percentage automatically adjusts to equal 100%.

    Split is selected
    Figure 1. You can adjust the split percentage using the arrow controls.
  5. From the top right corner of the main screen, select one of the following Save Configuration options (select the arrow to display hidden options):

    • Save Configuration (requires Full access): Saves the flag configuration, but does not turn Configuration on. The configuration is only activated when Configuration on is set. Refer to Managing feature releases to turn the configuration on.

    • Save & Activate Configuration (requires Full access): Saves the flag configuration, and turns Configuration on.

    • Request Changes: Saves the flag configuration and sends a request to all administrators for approval. The configuration is not activated, even if scheduled to do so. Refer to Requesting approval for flag configurations for more information.

Split releases can be scheduled. The configuration must be on for a scheduled feature release to occur. For more information, refer to Scheduling a feature release.

The implications of updating a live flag

Decreasing a live flag’s true percentage changes the flag consistency for some users.

To preserve the consistency of the user experience, it is not recommended to decrease a live flag’s true percentage. If a flag’s true percentage is decreased, some users may not receive a true value even if they have previously received one.

While it is not recommended to update any flag that is already live in production, if changes are needed, you can safely increase a flag’s true percentage.

When a flag’s true percentage is increased, all existing users that received a true value will continue to have a consistent experience.

How the algorithm works

The split release flag algorithm works as follows:

  • The client-side SDK generates a UUID (called rox.distinct_id) and serializes it on the device.

  • Every feature flag has its own seed to remove any potential statistical bias between 2 feature flags.

  • The SDK uses the seed and distinct_id to run a hash function that is mapped to a double number from 0-1.

If you select a 50% split, for example, then CloudBees Feature Management checks if the hash result is smaller than 0.5.

Overriding a distinct_id with a user id You can choose to override the distinct_id with a user ID to support the following:

  • A consistent cross-platform behavior for split releases.

  • A consistent experience for backend SDK users.