Creating audience-based releases

This topic explains how to create an audience-based release to roll out changes to specific audiences in sequence.

Prerequisites

To create an audience-based release, you should first complete the following prerequisites:

• Choose a context kind
• Define your audiences

Choose a context kind

Choose a context kind to use as the randomization unit for the rollout. The context kind determines how LaunchDarkly assigns traffic to variations and how audiences are evaluated during each phase. It must be available in both the flag or AgentControl config and in any metrics you plan to monitor.

If this is your first audience-based release, read Setting up contexts for guarded rollouts to learn more about best practices for setting up and choosing contexts.

Create metrics

If you are using guarded rollout behavior, choose one or more existing metrics or create new ones to monitor during the rollout. All phases share the same metrics and rollback configuration. To learn how, read Creating and managing metrics.

Define your audiences

Decide which audiences to include and in what order. Each audience defines which contexts are included in a phase of the release. You can define audiences using segments or targeting rules.

Create an audience-based release

You can create an audience-based release when you begin serving a new variation. This applies whether you are toggling the flag or AgentControl config on for the first time, or changing a variation on a flag or config that is already on.

To create an audience-based release on a flag or AgentControl config:

1. Navigate to the flag or config you want to release, then select the Targeting tab.
2. Locate the rule where you want to create the release.
3. Click Ship it or the “using a release is recommended” release policy banner.

4. Select the rollout variations.
5. Select the context kind to use as the randomization unit.
6. (Optional) Select metrics or metric groups to monitor for regression.
7. Configure the rollout steps. These settings apply to every phase in the release.
8. Select a Phase advancement option. Automatic phase advancement starts each phase for you as soon as the current phase completes. LaunchDarkly handles the transition between audiences for you.
   • Select Manual to start each phase yourself after the current phase completes.
   • Select Automatic to let LaunchDarkly start the next phase for you as soon as the current phase completes.
9. Select a “Final phase” option.
10. Click Health check waiting or Health warnings to review any issues that could prevent LaunchDarkly from monitoring your rollout. To learn more, read Health checks for guarded rollouts.
11. Click Review and save.

After you save, LaunchDarkly starts the rollout for the first audience. The remaining phases exist in a configured state but do not begin until the previous phase completes.

Advance to the next phase

How a release moves between phases depends on the phase advancement option you selected when you created the release.

A phase completes when the rollout steps reach 100% for the current audience.

Manual phase advancement

If you selected Manual phase advancement, you must start the next audience yourself.

To advance to the next phase manually:

1. Navigate to the flag or AgentControl config and select the Targeting tab.
2. Confirm that the current phase’s rollout steps have reached 100% before proceeding.
3. Click Advance to next phase.

Automatic phase advancement

If you selected Automatic phase advancement, LaunchDarkly starts the next phase automatically when the current phase completes. LaunchDarkly manages the transition for you.

Monitor an audience-based release

To monitor an audience-based release:

1. Navigate to the flag or AgentControl config.
2. Select the Monitoring tab.
3. Review the current phase and rollout progress.
4. Examine metric performance for the active audience.
5. Check for regressions or health warnings.

If LaunchDarkly detects a regression, you can roll back the release manually, or automatic rollback takes effect if you configured it. To learn more, read Managing guarded rollouts.