Phases let you plan a feature flag’s whole rollout in an environment up front, from the first internal users to everyone, and move through it one stage at a time. This page covers adding phases, setting triggers so phases turn on by themselves, and turning phases on and off by hand to move a rollout forward or roll it back.
Phases and triggers
A phase is a stage in a flag’s rollout in one environment, such as “Internal”, “10% of users”, or “Everyone”. Each phase holds one or more rules. When a phase is on, its rules join the rules from the phases before it, so every phase you turn on widens the rollout.
Phases are ordered, and they turn on in that order. A phase can’t be on while a phase before it is off. Turning a phase off removes its rules from the rollout and rolls the flag back to the users that earlier phases still target.
A trigger turns a phase on without anyone having to do it. Each phase can have one trigger. A phase can turn on at a specific date and time, or a set delay after the phase before it turns on. A phase without a trigger waits for someone to turn it on.
Triggers chain. If phase 2 starts 1 day after phase 1, and phase 3 starts 2 days after phase 2, turning on phase 1 sets the whole rollout in motion. Each delay counts from when the phase before it actually turned on, so if you hold phase 2 back by turning it on by hand later, phase 3 moves back too.
Use phases when you want a planned, staged rollout in an environment. If you only need to target a fixed group of users, rules on their own are enough.
Add a phase
Add a phase for each stage of the rollout. The first time you add a phase to an environment that already has rules, those rules become the first phase.
Before you begin
You’ll need:
- A feature flag with the environment added to it. See Turn on a feature flag for an environment.
To add a phase:
- From your project, select Feature Flags, then select the flag.
- In the Environments section, select the environment.
- Select Add, then select Phase.
- Enter a Phase Name that describes the stage.
- Add one or more rules to the phase. See Add a rule.
- Save the flag.
The new phase appears at the end of the environment’s phase list. It’s off until you turn it on or its trigger fires.
A phase can’t be empty. Removing a phase’s last rule removes the phase, including its trigger. To start a new phase from an existing one, open the phase’s menu and select Clone phase.
Phase triggers
A phase’s trigger decides when the phase turns on. This table lists the trigger types you can choose in the phase’s trigger settings.
| Trigger | Settings | Turns the phase on |
|---|---|---|
| Manual | None | Only when someone turns it on. |
| After a delay | Delay and Unit (hours or days) | The given time after the phase before it turns on. Not available on the first phase. |
| Specific date/time | Date, Time, and Timezone | At the given date and time in the given timezone. |
Delays are exact durations, so a 24-hour delay that crosses a daylight saving change is still 24 hours. A Specific date/time trigger still waits for the phases before it: if an earlier phase is off when the date passes, the phase turns on after the earlier phases do.
For example, a Production rollout might start an “Internal” phase manually, start “10% of users” After a delay of 1 day, and start “Everyone” at a Specific date/time of Monday at 9:00am in the team’s timezone.
Set a phase trigger
Set a trigger to turn a phase on automatically, so the rollout keeps moving outside working hours or without someone watching.
To set a phase trigger:
- From your project, select Feature Flags, then select the flag.
- In the Environments section, select the environment.
- Select the phase’s trigger. [VERIFY: the name or position of the control that opens a phase’s trigger settings — needs: confirmation from the phase list UI]
- Select the trigger type.
- Enter the trigger’s settings.
- Save the flag.
The phase shows when it’s due to turn on, such as “Triggers in 2 days”. Octopus checks for due triggers with a scheduled server task [VERIFY: how often the task runs and whether it appears in the Tasks list — needs: confirmation from the feature flags team], so a phase can turn on a short time after its due time.
If a trigger’s time has already passed when you save, for example because you set a date in the past, Octopus asks you to confirm in a Save and Trigger Phases dialog. Saving turns those phases on straight away, along with any later phases whose triggers also become due.
Turn a phase on or off
Turn a phase on by hand to start a rollout or move it forward early. Turn a phase off to roll the flag back to the users that earlier phases target.
To turn a phase on or off:
- From your project, select Feature Flags, then select the flag.
- In the Environments section, select the environment.
- Select Turn this phase on or Turn this phase off on the phase.
- Save the flag.
The phase shows as on or off in the environment’s phase list, and applications in the environment get the new result after Octopus publishes the change.
Because phases turn on in order, a phase can only be turned off while every phase after it is off. [VERIFY: whether turning a phase off in the UI also turns off the later phases, or blocks the change until they’re off — needs: confirmation from the phase list UI]
Turning a phase off also clears the time it turned on. If the next phase has an After a delay trigger, its delay starts again from when you turn the earlier phase back on.
To stop a flag for everyone in the environment straight away, turn off the environment’s switch instead.