Scheduled Flag Changes in Flagsmith
A complete, plain-English guide to making a flag change itself at the exact moment you choose: how scheduling works, what it can and cannot do, how it meets approvals, time zones and caching, and how to plan, test, monitor, cancel and debug a change that happens while you are asleep.
Imagine your shop’s big festive sale begins at midnight. The new banner, the discounted prices and the faster checkout must all appear at the same moment, not five minutes earlier and not twenty minutes later. Nobody on the team wants to be awake at midnight, clicking switches with tired hands and hoping nobody mistypes a value. What the team wants is to prepare everything calmly in the afternoon, check it twice, and let the system do the exact thing at the exact time. That is the promise of scheduled flag changes.
Flagsmith is an open-source feature flag and remote configuration service. A feature flag is a switch in your application that decides whether some behaviour is active, and Flagsmith stores that decision outside your code. A scheduled change is a flag change that is prepared now but applied later, at a date and time you choose. Because the flag lives outside the code, the change needs no deployment. It simply happens when its time arrives.
This guide starts from the first idea and builds step by step. You will learn what a scheduled change really is, where it lives in the dashboard, how it behaves around time zones, approvals and caches, how to plan launches, shutdowns and ramps, how to test and verify them, and how to find the cause when something does not happen on time. No prior knowledge of Flagsmith is assumed and no code is needed. Scheduling options depend on your plan and version, and menu names change between releases, so treat the screens described here as signposts and confirm details in your own dashboard and the official documentation.
1Why Time Matters in Releases
Some changes are only right at a certain moment. Doing them by hand, live, is the riskiest way to meet that moment.
Releases have deadlines
Most changes can happen whenever the team is ready. Some cannot. A sale starts at a published time. A new feature is announced in a keynote and must be live as the speaker says “available now”. A regulatory change takes effect on the first of the month. A partner’s maintenance window begins at two in the morning and your integration must be switched off before it starts. In each case the moment is fixed by something outside your control, and the work of the team is to be ready at that moment, not before and not after.
The human problem
The traditional answer is to put a person on duty. Someone stays up, watches the clock and flips the switch. This works, but it has costs. People get tired and make slips at the worst hour. Time zones turn an ordinary launch into a night shift for someone. Nerves rise as the minute approaches, and a mistyped value in a hurry can turn a launch into an incident. The more important the moment, the more likely a human is to be nervous at it.
The scheduled answer
A scheduled change moves the hard work earlier. The team prepares the exact change in daylight, reviews it with fresh eyes, perhaps gets it approved by a colleague, and then leaves it waiting. At the chosen time the system applies it, identically to how it was prepared. People are still responsible for watching the result, but the risky act of typing and clicking under pressure has been removed.
A house with a timer on the garden lights does not need someone to walk outside every evening at dusk. You set the timer once, in comfort, and the lights come on by themselves. If the timer is wrong, you notice and fix it. If the sun sets earlier in winter, you adjust it. A scheduled flag change is the same kind of timer, with a few more safeguards and a few more things that can go wrong if you set it carelessly.
Real-world example: timed launches at retailers
Large online retailers such as Amazon have publicly run sales events that begin at announced times, where prices, banners and features change together for millions of shoppers. Making such a moment work depends on preparing changes in advance and applying them on schedule, with a human team watching afterwards instead of racing to type during the countdown.
Whenever you hear “at midnight” or “when the announcement goes out”, ask a single question: could this be prepared and scheduled in advance? If yes, schedule it. Reserve live clicking for the surprises you could not have planned.
2The Vocabulary: Ten Words You Need
A small set of terms describes everything in this guide. Learn them once and every later chapter reads easily.
Feature flag
A named switch in your application, with an optional value, whose state is stored in Flagsmith instead of your code.
Environment
A separate copy of settings, such as Development, Staging or Production, each holding its own flag states.
Scheduled change
A flag change prepared now and applied automatically at a chosen future date and time.
Go-live time
The exact date and time at which a scheduled change should become the live state. Some versions call it “live from”.
Change request
A proposed flag change that must be approved by a colleague before it takes effect. Available on some plans.
Version
A saved state of a flag. In versioned setups, a scheduled change can be a future-dated version waiting to become live.
UTC
Coordinated Universal Time, the neutral world clock that systems use inside, then show in local time to people.
Task processor
The background part of Flagsmith that carries out timed jobs. Self-hosted installations must keep it running.
Cache
A stored recent answer that saves asking again. Caches decide how soon users see an applied change.
Audit log
A diary kept by the system of who changed what and when, including changes that applied on schedule.
flowchart LR
P["Prepare the change in daylight"] --> R["Review and approve"]
R --> W["Waiting: pending scheduled change"]
W --> T["Go-live time arrives"]
T --> A["Flagsmith applies the new state"]
A --> C["Caches refresh"]
C --> U["Users see the change"]
Read the figure from the left. The team prepares the change in daylight, and a colleague reviews and approves it. The change then waits as a pending scheduled change. When the go-live time arrives, Flagsmith applies the new state. After that, caches in your servers and apps refresh, and users finally see the change. The key lesson is that applying and seeing are two separate moments, and the gap between them is the subject of Chapter 9.
A train timetable has a published departure, and the train leaves the station at that time. Passengers further down the line only see it arrive minutes or hours later, depending on distance. The departure is when Flagsmith applies the change. The arrival at each passenger’s station is when each cache refreshes and each user sees it. Both matter, and they are not the same moment.
Scheduling is applied to a flag in one environment at a time. A change scheduled in Staging does not schedule anything in Production. Each environment has its own pending changes and its own clock of events.
3What a Scheduled Change Is, and What It Is Not
Understanding the exact nature of a scheduled change prevents the most common misunderstandings about it.
A scheduled change is a prepared state
A scheduled change is a description of how a flag should look at a future moment. It says, for example, “at one minute past midnight on the fifteenth, this flag should be enabled with this value”. When that moment arrives, Flagsmith makes the flag look like that description. It is not a series of clicks replayed later. It is a target state applied all at once.
It is applied by the server, not by devices
The time is checked by Flagsmith’s own systems, not by the clocks on users’ phones or browsers. This matters. If the change were decided by each device’s clock, a user who set their phone clock forward could see the feature early, and users in different places would see different results for the same moment. Because Flagsmith applies the change centrally, the flag changes once, for everyone, and devices simply learn the new state the next time they ask or refresh.
It is not a real-time guarantee to the second
Scheduled changes are carried out by a background worker that checks for due work regularly. The change will be applied at or very shortly after the chosen time, typically within a minute or so, but it is not a precision instrument measured in milliseconds. If your launch depends on being exact to the second, such as a ticket sale where fairness is judged to the second, combine scheduling with other design choices, such as a waiting room, instead of relying on the flag’s timing alone.
| Question | Answer | Why it matters |
|---|---|---|
| Who checks the time? | Flagsmith’s servers | Device clocks cannot cause early or late exposure |
| Is it exact to the second? | No, usually within about a minute | Plan a small margin around critical moments |
| Does it need a deployment? | No | But the code that reads the flag must already be live |
| Does the user see it instantly? | No, caches add a delay | Allow lead time for the change to spread |
| Is it per environment? | Yes | Scheduling in Staging does nothing in Production |
| Can it be cancelled? | Yes, before it applies | A wrong plan can be removed without harm |
A school bell rings at the scheduled time, rung by the school’s own clock. Pupils in far corners of the building hear it a moment later, and nobody sets the lesson length by their own watch. If a pupil’s watch is fast, the bell still decides when the lesson ends. A scheduled flag change works the same way: one authority rings the bell, everyone else responds to it.
Common misunderstandings
“It will deploy my code”
It will not. Scheduling flips a flag, and the code that reads the flag must already be running in that environment.
“Users see it at the exact second”
Caches and refresh periods add a delay, usually seconds to minutes, and sometimes longer on devices.
“It can run any complex plan”
It applies target states. Anything beyond that, such as conditional logic, belongs in your code or your automation.
“Scheduling is a security tool”
It controls timing, not access. Do not rely on a timed flag to keep something confidential.
The most expensive misunderstanding is believing that scheduling a flag also prepares the code. Always confirm that the build which reads the flag is deployed to the target environment before the go-live time.
4Where Scheduling Lives in the Dashboard
There is more than one road to a scheduled change. Which one you see depends on your plan and your version of Flagsmith.
Scheduling from the flag editor
The most direct route is the flag’s own edit screen. Where scheduling is available, the save area offers a way to choose a future date and time instead of saving the change immediately. You prepare the new state, such as enabling the flag or setting a new value, pick the go-live time and confirm. The change is stored as pending, and the flag’s live state stays as it is until the time arrives.
Scheduling through a change request
On plans with change requests, a proposed change can carry a go-live time. The request is reviewed and approved by a colleague, and once approved it is applied at the time you chose, or immediately if no time was set. This route combines two safeguards: a second pair of eyes before the change is accepted, and a machine that applies it exactly as approved.
Scheduling with feature versioning
In environments that use feature versioning, each saved state of a flag is a version. A change can be saved as a version that goes live at a future time. The list of versions then shows a past, a present and perhaps several future versions, each waiting for its moment. Versioning also makes it easy to see what the flag looked like at any point, which helps when reviewing what happened after a launch.
| Route | Safeguards | Best for | Often needs |
|---|---|---|---|
| Flag editor with a future date | The person’s own care | Simple timed changes in lower environments | A plan that includes scheduling |
| Change request with a go-live time | Review and approval | Production launches | A plan with change requests |
| Future-dated version | Version history | Planned sequences and clear audit | Feature versioning turned on |
| Automation through the API | Your own pipeline | Large or repeatable plans | Tokens and a pipeline |
Posting a letter can be done in several ways. You can drop it in a box yourself, which is quick and relies on you. You can ask a colleague to check the address before it goes, which is safer. You can book it with a service that records and delivers it on a chosen date, which is clear and traceable. The destination is the same, the care and the paper trail differ.
Plans and availability
Scheduling features have historically belonged to paid plans, and the exact set can differ between the hosted service and self-hosted installations. Before building a process around scheduling, check which routes your account offers. If it does not offer native scheduling, you can still reach a similar outcome using automation, which Chapter 22 describes, though you take on the responsibility of making that automation reliable.
Open a Staging flag today and look for the scheduling option. Knowing exactly where your version puts it, and what it is called, removes confusion from the first time you need it under pressure.
5The Life of a Scheduled Change
A scheduled change passes through a handful of states. Knowing them tells you what you can still do at each moment.
flowchart TD
A["Created and saved as pending"] --> B{"Approval required?"}
B -- "Yes" --> C["Waiting for reviewer"]
C --> D{"Approved before go-live?"}
D -- "No" --> E["Not applied on time, needs attention"]
D -- "Yes" --> F["Approved and waiting"]
B -- "No" --> F
F --> G{"Go-live time reached?"}
G -- "No" --> H["Can still be edited or cancelled"]
H --> F
G -- "Yes" --> I["Applied: becomes the live state"]
I --> J["Recorded in the audit log"]
F --> K["Cancelled by a person"]
The figure starts when a change is saved as pending. If your plan requires approval, it waits for a reviewer, and if the reviewer does not approve before the go-live time, the change is not applied on time and someone must act. Once approved, or if no approval is needed, the change waits for its moment. While it waits, a person can still edit or cancel it. When the go-live time is reached, the change is applied and becomes the live state, and the action is recorded in the audit log.
What you can do in each state
Pending
The change exists but is not live. You can inspect it, edit it, move its time or delete it with no effect on users.
Awaiting approval
A reviewer reads the difference and approves or rejects. The clock keeps running while they decide.
Approved and waiting
Everything is ready. The remaining job is to make sure nothing else changes that would make the plan wrong.
Applied
The live state now matches the plan. To undo it you must make a new change, not cancel the old one.
Superseded or cancelled
Either a later change replaced it or a person removed it. History keeps a record that it existed.
A parcel booked for delivery next Tuesday can be changed, redirected or cancelled while it waits in the depot. Once the van has delivered it, the parcel is at the door and the only way to reverse the event is to arrange a return. A scheduled change has the same shape: flexible before its moment, final once it has happened.
Do not assume you can cancel a change at the last moment. Between the instant the worker begins to apply it and the instant you see the result, nothing can be stopped. If you doubt a plan, remove it well before its time, not in the final seconds.
6What You Can Schedule
A scheduled change can carry more than an on-or-off position. Knowing its reach helps you plan whole moments with one saved change.
The main position
The simplest thing to schedule is the flag’s enabled position: switch on at a time, or switch off at a time. This covers launches, shutdowns, maintenance windows and expiry. Because it affects everyone in the environment who reaches the flag, it is also the highest-impact change, and deserves the most careful review.
The value
If a flag carries a remote value, such as a banner message, a price label or a numeric limit, the scheduled change can set a new value to take effect at the time. This is the usual way to change a campaign message at the end of a promotion, or to raise a limit at the start of a new plan year. Values are visible to client applications, so never schedule a secret or private value, even for a moment.
Variants and overrides
Depending on your plan and version, a scheduled change can also include multivariate allocations and segment overrides. That lets you plan complex moments, such as “from nine in the morning, premium customers see variant B, everyone else the default”. Support for these pieces differs between versions, and this is an area where behaviour is easy to assume wrongly, so test in Staging that the pieces you need are included in the scheduled state and applied together.
| Piece | Can it usually be scheduled? | Example | Caution |
|---|---|---|---|
| Enabled position | Yes | Turn on the sale banner at midnight | Highest impact, review carefully |
| Remote value | Yes | Change the banner text at the end of the sale | Values are visible to clients |
| Multivariate split | Depends on version | Start an experiment on Monday | Test that the split is included |
| Segment overrides | Depends on version | Open a feature to staff at nine | Check priority order after applying |
| Identity overrides | Depends on version | Rarely scheduled | Personal and environment-specific |
A theatre crew’s cue sheet says what should happen at each moment: lights down, curtain up, music in. Each cue can change several things at once. A good cue sheet lists every change in the cue, so the stage manager is not surprised by a missing one. Think of each scheduled change as a cue: write down everything it should do, and check that the system really includes all of it.
One flag or several?
Complex moments often involve several flags. Scheduling each separately for the same time sounds simple, but the changes are applied one after another by a worker, not truly simultaneously. For a moment they may be out of step. If flags must change together, consider whether they should be one flag, or whether your code can tolerate a short period in which some are new and some old. Chapter 12 explains how to design for this.
Real-world example: campaign copy changing on a clock
E-commerce and media companies commonly change banners, prices and headlines at the start and end of campaigns, and have publicly described using configuration systems for this instead of releases. Treating text and limits as scheduled configuration lets marketing and product teams move at the pace of the calendar, not the pace of the deployment pipeline.
7Time Zones, UTC and the Trouble with “Midnight”
More scheduled launches go wrong because of time zones than because of bugs. A little care here pays back every time.
What is a time zone problem?
The Earth is divided into time zones, so the same instant has different clock readings in different places. Midnight in Delhi is lunchtime of the previous day in New York. Many systems store times in one neutral zone called UTC, and convert to local time only when showing them to a person. When a person types a time into a form, the question “in whose time zone?” must have a clear answer, and mistakes there shift a launch by hours.
How Flagsmith treats times
Dashboards generally show and accept times in the browser’s local time zone, and the system stores them in a single standard internally. That is convenient, since you type the time on your own clock, and risky, since a colleague in another country looking at the same change sees a different local time for the same instant. Confirm in your own dashboard which zone a pending change displays, and prefer to write the intended time, with its zone, in the change’s description.
Common time traps
Daylight saving shifts
In places that change clocks, a “same time next week” plan can move by an hour. Two or three days of the year have missing or doubled hours.
Midnight is ambiguous
“Midnight on the fifteenth” can mean the start or the end of that day. Write “00:01 on the fifteenth” or “23:59 on the fourteenth” instead.
Wrong zone in the picker
A person travelling or using a laptop set to a different zone may pick a time that is hours out.
Date formats
Day-month-year and month-day-year readings of the same digits differ. Spell out the month name in plans and messages.
| Intended moment | Mistake | Result | Safer practice |
|---|---|---|---|
| Sale begins 00:00 IST on the 15th | Picked 00:00 in a UTC-based laptop zone | Starts 5.5 hours late, at 05:30 IST | Check the zone shown beside the time |
| Feature ends 23:59 on the 31st | Typed 00:00 on the 31st | Ends a day early | Use an explicit end time on the correct date |
| Launch at nine in New York in March | Planned in winter offset | One hour out after the clocks changed | Convert at the date of the event, not today |
| Launch 03/04 | Read as 3 April, meant 4 March | Weeks out | Write “4 March” in full |
A conference call across continents is easy to ruin with a loose phrase like “ten o’clock”. Whose ten? Experienced organisers write “10:00 IST, 05:30 UTC, 06:30 in London” in the invitation, so nobody has to guess. A scheduled change deserves the same treatment: every plan should state the moment in at least two clocks.
A habit that prevents most problems
Write the moment in UTC and in local time
Put both in the change’s description and in the team channel announcement.
Have a second person check the zone
Reviewers should confirm the displayed zone, not only the digits.
Rehearse in Staging at a nearby time
Schedule a harmless change ten minutes ahead, and check that it fires when you expect.
Avoid clock-change weekends
Keep important launches away from the days when local clocks change, where you can.
If your audience spans countries and the launch must feel simultaneous for everyone, a single instant in time is correct but may be a bad hour for some. Decide deliberately between one global moment and several local ones, as Chapter 16 describes.
8How the Scheduler Actually Runs
A timer that fires at the right moment is a small machine with moving parts. Knowing the parts explains both its strengths and its limits.
The pending list and the worker
When you save a scheduled change, Flagsmith stores it with its go-live time and marks it pending. Nothing happens to the live flag. Separately, a background worker, often called the task processor, wakes up at regular short intervals and asks a simple question: is any pending change due? If the answer is yes, the worker applies that change to the live flag and records the event. If not, it goes back to sleep until the next interval.
sequenceDiagram
participant PE as Person
participant FS as Flagsmith API
participant DB as Database
participant TP as Task Processor
participant SDK as SDK or App
PE->>FS: Save change with go-live time
FS->>DB: Store as pending
loop Every short interval
TP->>DB: Any pending change due now?
end
DB-->>TP: Yes, this change is due
TP->>DB: Apply new state as the live state
TP->>DB: Write an audit log entry
SDK->>FS: Ask for flags
FS-->>SDK: Return the newly applied state
The figure shows a person saving a change, and Flagsmith storing it as pending in the database. The task processor repeatedly checks whether anything is due. When a change is due, the processor applies it as the new live state and writes an audit entry. From then on, any SDK or app that asks Flagsmith for flags receives the new state, subject to the caches between them. At no point does a person need to be present at the moment of application.
Why it is not exact to the second
Because the worker checks at intervals, a change is applied at the first check after its time, not at the precise instant. If the worker checks every minute, a change due at noon is applied somewhere between noon and a minute past. Under heavy load or a short outage of the worker, it may be a little later still. For most launches this is invisible. For anything where seconds matter, plan the margin into the design.
Self-hosted installations
On the hosted Flagsmith service, the worker is part of the platform and is run for you. If you host Flagsmith yourself, the worker is a separate process that you must run, monitor and keep healthy. A missing or crashed worker is a silent cause of changes that “just did not happen”. Treat it as a production service with its own alarms, and test scheduling after every upgrade of your installation.
A caretaker who walks the school corridors every five minutes to ring the bell when a lesson ends is reliable, but not exact. If the lesson ends at 10:00, the bell rings when the caretaker next passes after 10:00, which could be at 10:00 or at 10:04. If the caretaker is ill, the bell does not ring at all until someone notices. The worker plays the role of the caretaker, and the pending list is the timetable on the wall.
Pending list
The stored plan: what to change, where and when.
Worker
The background process that checks for due changes and applies them.
Live state
What Flagsmith currently returns to SDKs. The worker updates it at the go-live time.
Audit log
The diary that records the application, with the time it actually happened.
For self-hosted installations, set up a simple alarm that fires when the worker stops, and a monthly rehearsal that schedules a harmless Staging change a few minutes ahead. A quiet worker looks identical to a healthy one until a launch depends on it.
9Applied Is Not Seen: Propagation and Lead Time
The moment Flagsmith applies a change and the moment every user sees it are separated by a chain of memories. Planning for the gap avoids many launch-night surprises.
Layers of memory
Between the dashboard and a user’s screen sit several layers that remember recent answers so they need not be fetched again. Your application may keep flag values in memory for a while. Client SDKs on phones and browsers may store results on the device. Server SDKs using local evaluation download the rules and refresh them on a timer, often about once a minute by default. A proxy or delivery network in front of Flagsmith may hold answers briefly. The total delay from application to the last user is the sum of these layers in the slowest path.
A short mixed period
For a short period after a scheduled change applies, some servers and devices still show the old state while others show the new. A user might see the sale banner on one page and not on the next. The mixed period ends when every cache has refreshed. Well-designed applications tolerate it, behaving safely and consistently whichever answer arrives. If your feature cannot survive two servers briefly disagreeing, the problem lies in the feature’s design, not in the schedule.
Choosing the lead time
If the public announcement says “live at midnight”, users will start refreshing at midnight, and some will arrive before the caches have turned over. You can solve this by moving the schedule slightly earlier than the announced moment, by a margin bigger than your longest cache delay. This is called lead time. A change scheduled at 23:58 for a midnight announcement gives the worker and caches two minutes to finish their work before the crowd arrives.
| Your slowest cache layer | Typical delay | Suggested lead time | Reason |
|---|---|---|---|
| Fresh requests with no caching | Seconds | 2 minutes | Covers worker interval and small delays |
| Local evaluation, one minute refresh | Up to about a minute | 3 to 5 minutes | Covers worker plus one full refresh |
| Mobile apps caching flags for several minutes | Several minutes | 10 to 15 minutes | Covers the slowest devices that matter |
| Delivery network with its own hold time | As configured | Longer than the hold time | Must outlast the proxy layer |
A shop that wants its doors to open to customers at nine does not turn the lights on at nine. It arrives at half past eight, switches on the lights, warms up the tills and stocks the shelves, so that at nine everything is ready. A scheduled change should behave the same way, applied a little before the public moment so the caches have warmed.
The opposite problem: leaking early
Lead time has a cost. If the feature is visible a few minutes early, a few users may see it before the official moment. For a marketing launch this is usually harmless. For something with a real embargo, such as unreleased prices or contractual announcements, early visibility may be unacceptable. Weigh both risks. Where an early peek would cause harm, hide the sensitive content behind a second control, such as a server-side check, instead of relying on the schedule alone.
Real-world example: configuration pushed close to traffic
Companies that serve huge traffic, such as Netflix, have publicly described caching configuration close to where it is used so no central service is asked on every request. That makes systems fast and resilient, and it also means a change spreads over a short, measurable interval. The same property is why a scheduled flag change needs a lead time.
Measure your real propagation delay in a quiet period before relying on it. Schedule a harmless Staging change, then record how long each kind of client takes to show it. Real measurements beat assumptions on launch night.
10Scheduling Together with Approvals
Approvals and schedules are two separate safeguards, and each has its own clock. Their interaction is where good plans quietly fail.
Two different questions
Approval answers “should this change happen at all?” Scheduling answers “when should it happen?” They are independent. A change can be approved and scheduled for tomorrow, approved with no schedule so it applies at once, or scheduled but not yet approved. Mixing them up leads to a classic problem: someone schedules a change for midnight, goes home, and assumes it is safe. If it was never approved, nothing happens at midnight, and nobody is awake to notice.
Approval before the go-live time
Submit early
Raise the request with its go-live time well before the event, ideally a full working day ahead, so reviewers are not racing the clock.
Name the reviewer
Tell a specific person it is waiting. A request that nobody was asked to look at can sit untouched for days.
Review both the content and the time
Reviewers should confirm that the state is right and that the date, time and zone match the plan.
Confirm the approval landed
Look at the request list the day before. “Approved and scheduled” is the state you want to see.
Have a fallback owner
Agree who may act if the plan is not approved in time, and what they should do.
What if approval arrives late?
Behaviour differs between versions and settings. In some arrangements, a change approved after its go-live time applies immediately. In others, it may be marked as missed and need to be rescheduled. Read the documentation for your version and test the case in Staging, because you want to learn the answer on a quiet afternoon, not on the night of a sale.
A wedding has a booked time at the venue and a licence from the registrar. The booking says when, and the licence says whether. A couple with a booking and no licence can arrive at the right moment and still not be married. A scheduled flag change with a time and no approval is exactly that: perfectly timed, and quietly invalid.
| Situation | What happens | Risk |
|---|---|---|
| Approved before go-live | Applied at the scheduled time | The intended outcome |
| Not approved by go-live | Not applied on time, or applied on approval | A silent miss or a late launch |
| Rejected by the reviewer | Never applied | The team must replan under time pressure |
| Edited after approval | May need approval again, depending on settings | A late edit can undo the approval |
Real-world example: regulated industries and four-eyes review
Banks, insurers and health companies commonly require that changes affecting customers be approved by someone other than the author, whether the change is code or configuration. Timed flag changes carry the same requirement, and teams in these industries usually treat the approval as the real deadline and the schedule as the delivery mechanism.
Make “approved and scheduled” a visible checkpoint in your launch plan, one day before the event, with a named person who confirms it. A tick on a shared checklist beats a hopeful memory.
11Several Changes, Several Hands: Order and Conflict
A single scheduled change is simple. A calendar full of them, edited by several people, needs a few rules to stay safe.
Changes apply in time order
If a flag has several pending changes, they apply in the order of their go-live times. A flag might be enabled at nine, have its value changed at noon and be disabled at six. At any moment, the live state is whichever change applied most recently. That is easy to reason about when all the changes are planned together, and confusing when different people add changes at different times without looking at what is already waiting.
Live edits can be overwritten
A scheduled change is a target state prepared earlier. If someone edits the live flag by hand after you scheduled your change, and your change applies later, it may replace their edit with the state you prepared. Depending on your version and whether versioning is on, the new state may be built from the older snapshot instead of the latest live state. The result is a surprise: a manual fix made at 11 a.m. is wiped by a scheduled change prepared at 9 a.m. and applied at noon.
flowchart TD
A["09:00 Live: enabled, value A"] --> B["10:00 Scheduled change prepared: value B at 12:00"]
A --> C["11:00 Manual edit: value C, to fix a problem"]
B --> D["12:00 Scheduled change applies"]
C --> D
D --> E{"Did the plan include the manual edit?"}
E -- "No" --> F["Live value becomes B, the manual fix is lost"]
E -- "Yes" --> G["Plan was updated, live value is as intended"]
The figure shows two people acting on the same flag. One prepared a scheduled change at ten to set value B at noon. Another made a manual edit at eleven to set value C, perhaps to fix a live problem. At noon the scheduled change applies. If the plan was not updated to account for the manual edit, the live value becomes B and the fix disappears. If the plan was updated, the live value is as intended. The lesson is that every manual edit to a flag with pending changes should include a check of the pending list.
Rules that prevent conflicts
One owner per flag
Name the person who manages a flag’s calendar. Others ask the owner before editing live state.
Check the pending list first
Before any manual live edit, look at what is already scheduled and whether it will overwrite you.
Cancel or update after manual edits
If you change live state during an incident, update or remove the pending changes it affects.
Keep the calendar short
A flag with a dozen pending changes is hard to reason about. Prefer fewer, larger, clearer steps.
A shared household calendar with a dentist appointment entered by one person and a family trip entered by another works well until both land on the same day. Then someone has to choose. A good household checks the calendar before booking anything, and tells the others when it moves something. Flag calendars need the same courtesy.
During an incident, people switch flags by hand under stress. Add “check the pending list on this flag” to your incident runbook, so a rushed fix does not get quietly reversed an hour later by a forgotten schedule.
12Dependencies: Code Deploys, Linked Flags and the T-Minus Plan
A scheduled flag change is only one event in a launch. Its timing must fit with the others, or the launch falls apart in the gaps.
The code must come first
A flag change has no power over code that is not there. If the build containing the new feature is not deployed to the target environment by the go-live time, the flag turns on and nothing appears, or, worse, an older version of the code reads the flag in an unexpected way. The rule is simple: deploy first, verify, then let the schedule release. Deployment is a risky act and the flag change is a safe one, so put the risky act early and the safe act at the moment that matters.
Flags that must move together
Some launches need several flags to change together, such as a new screen, a new service behind it and a new price. Each scheduled change is applied separately by the worker, so there can be a brief period in which one flag has changed and another has not. If a half-changed state would break the product, redesign: combine the flags into one, or make the code safe when flags disagree, such as by checking both before showing the screen. Never rely on scheduling flags a few seconds apart to create an ordering your code depends on.
flowchart TD
A["T minus 7 days: plan agreed, owners named"] --> B["T minus 3 days: code deployed with flags off"]
B --> C["T minus 2 days: rehearsal in Staging"]
C --> D["T minus 1 day: changes submitted and approved"]
D --> E["T minus 2 hours: pending list checked, team briefed"]
E --> F["T minus 5 minutes: dashboards open, on-call ready"]
F --> G["T zero: scheduled change applies"]
G --> H["T plus 15 minutes: verify with test identities"]
H --> I["T plus 1 day: review and clean up"]
The figure lays out a launch as a countdown, where “T zero” is the go-live time. A week before, the plan is agreed and owners are named. Three days before, the code is deployed with all flags off. Two days before, the team rehearses in Staging. One day before, changes are submitted and approved. Two hours before, the pending list is checked and the team briefed. In the last minutes, dashboards are opened and on-call staff are ready. At T zero the change applies, fifteen minutes later the team verifies with test identities, and a day later the team reviews and cleans up. Almost all of the work happens before T zero, which is the whole point.
A rocket launch is a countdown of checks, not a single button press. Fuel, instruments, weather and crew are confirmed in a fixed order long before ignition. The final moment is brief because the long checklist before it removed every avoidable surprise. A flag launch is much smaller and benefits from the same discipline.
Dependency checklist
| Dependency | Question to ask | If it fails |
|---|---|---|
| Code deployed | Is the reading build live in this environment? | The flag does nothing or behaves oddly |
| Database changes | Is the data ready for the new behaviour? | Errors appear when the feature turns on |
| Partner services | Are they ready at the go-live time? | A feature that works for us but not for them |
| Other flags | Which flags must be in place first? | Half-working features |
| Content and translations | Are all texts and images ready? | Blank or untranslated screens at launch |
| Support and sales teams | Do they know the time and the change? | Confused customers and slow answers |
Write the countdown as a short document and share it with everyone involved, including non-technical colleagues. When support and marketing know the plan, a quiet launch feels calm for everyone, not just for engineers.
13Pattern: The Timed Launch
The most common use of scheduling is the plain launch: something goes live at a chosen time. Even this simple pattern benefits from a few good habits.
What a timed launch looks like
The flag is off in Production and the code is deployed. The team prepares a change that enables the flag, with any new value, at the launch time, minus the lead time from Chapter 9. After approval, the change waits. At the go-live time the worker applies it, caches refresh, and users see the feature. The team watches, verifies and, if all is well, continues with a gradual rollout or leaves it fully on.
Launch to everyone, or to a slice first?
A launch to everyone at once is simple and dramatic, and carries the whole risk in one moment. A launch to a slice first, using staff, a beta group or a small percentage, shrinks the risk and lets you spot problems early. Many teams combine both: schedule an early, small step days before the public moment, then a final step to everyone at the announced time. That way the feature has already met real traffic by the time the crowd arrives.
Three days before: staff only
A scheduled change enables the flag for the staff segment. Employees use the real feature on real accounts and report problems.
Two days before: a small percentage
A second scheduled change raises the audience to a small share of eligible customers, with guardrails watched.
One day before: confirm and freeze
The team confirms health, approves the final change and agrees to freeze other edits to the flag.
Launch moment: open to everyone
The final scheduled change enables the flag for the whole audience, a few minutes ahead of the announcement.
After: verify and relax the freeze
Test identities confirm the live state. Guardrails stay open for the first hours. The freeze ends when the team is satisfied.
A theatre does not open a new production to a full house on the first night with no previews. Friends and family see a dress rehearsal, then a preview night for a small paying audience, then opening night for everyone. By opening night, the surprises have already happened in front of forgiving audiences. A staged scheduled launch follows the same shape.
Name the change clearly
Use a title such as “Festive sale banner on, 14 Oct 23:55 IST” so anyone can understand the plan at a glance.
Add the rollback in the description
Write how to switch it off, who may do it and how long it takes to take effect.
Check the environment
Confirm the pending change is on Production, not Staging, the day before.
Announce internally
Tell support, sales and on-call staff the exact time in more than one time zone.
Real-world example: dark launches and staged reveals
Facebook has publicly described launching its Chat feature in 2008 through a dark launch, with the code running on real traffic before users could see it and exposure widened in stages. A scheduled launch built from earlier small steps follows the same instinct: let the surprises happen quietly before the public moment.
14Pattern: Timed Shutdowns, Maintenance Windows and Expiry
Scheduling is just as useful for switching things off. The end of something is often a fixed moment too.
Ending a promotion or a trial
Promotions end. A discount banner should disappear when the sale ends, not when someone remembers. Scheduling the end at the same time as the beginning, in one planning session, removes the chance of a sale banner still advertising a price that no longer exists. The same applies to free trials, beta programmes and seasonal features such as holiday themes.
Maintenance windows
When a partner service goes down for maintenance, or when you plan to move a database, you may want to switch off a feature that depends on it. A scheduled disable at the start of the window and a scheduled enable at its end keep customers from meeting errors, and keep people from having to stay awake for both transitions. Always add a margin at both ends, because real maintenance rarely starts and finishes exactly on time.
flowchart LR
A["Before window: feature on"] --> B["Scheduled disable, 10 minutes before"]
B --> C["Maintenance window: feature off, safe message shown"]
C --> D{"Maintenance finished and checked?"}
D -- "Yes" --> E["Scheduled enable, with margin after the window"]
D -- "No" --> F["Cancel the enable and extend the window"]
F --> C
E --> G["Feature on again, verify with test identities"]
The figure shows the feature on before the window, then a scheduled disable ten minutes before it starts. During the window the feature is off and customers see a safe message instead. When the work ends, the team checks that everything is truly ready. If so, the scheduled enable applies with a margin after the window. If not, the team cancels the enable and extends the window. This is the key safeguard: a scheduled enable should always be cancellable by a person who has just learned the work is not finished.
Time-boxed features and sunsets
Some features are meant to expire. A seasonal theme, a beta programme or an old API behaviour might end on a fixed date. Scheduling the end takes the decision out of the realm of forgotten tasks. It is wise to schedule the end of a temporary feature at the same time as its launch, and to add a reminder before the end date so someone can extend it if the plan has changed.
A shop putting up a sale sign usually sticks a note on the back: “take down on the fifteenth”. Without the note, the sign stays up for weeks, and customers argue at the till about prices that have already returned to normal. Scheduling the end of a promotion is the same note, written when the sign goes up.
| Situation | Scheduled action | Margin to add | Manual exit |
|---|---|---|---|
| Sale ends at midnight on the 20th | Disable banner and restore prices | A minute or two, to match the public promise | Extend if the sale runs long |
| Partner maintenance 02:00 to 04:00 | Disable at 01:50, enable at 04:15 | 10 minutes before, 15 after | Cancel the enable if work overruns |
| Beta programme ends on the 30th | Disable the beta segment’s override | Notify users days earlier | Extend by rescheduling |
| Old behaviour retired on the 1st | Disable the legacy flag | After all clients have updated | Switch back on if clients break |
A scheduled enable after maintenance is a loaded gun if the work overruns. The change will turn the feature on whether or not the dependency is ready. Keep a named person responsible for cancelling it, and check readiness before the time arrives.
15Pattern: Scheduled Ramps
A gradual rollout is a sequence of widenings. Scheduling can carry out the sequence, but it should never replace the watching that makes a ramp safe.
What is a ramp?
A ramp is a planned sequence of increasing audiences, such as staff only, then one percent of customers, then five, twenty-five, fifty and everyone. Each step exposes more people to the new behaviour, and between steps the team watches measurements to confirm that things are healthy. The usual tool for the audience is a percentage split inside a segment, whose threshold is raised at each step.
What scheduling adds
Scheduling lets you prepare the whole sequence in advance, with each rise at an agreed time, so the steps happen on the calendar and not on whoever’s availability. That is useful for weekends, holidays and distributed teams. It also makes the plan visible: a reviewer can see the entire ramp at once and judge whether the pace is sensible.
What scheduling must not replace
A ramp’s safety comes from checking health between steps. A scheduled sequence that raises the percentage on a timetable, regardless of results, removes exactly that check. If the one percent step reveals errors, a blindly scheduled five percent step makes things worse at the planned time. The sensible compromise is to schedule only the next step or two, never the whole ramp, and to extend the plan as each step proves healthy. The calendar then reflects confirmed progress, not hopeful promises.
flowchart TD
A["Step 1 live at 1 percent"] --> B["Schedule step 2 for tomorrow, 5 percent"]
B --> C{"Healthy when the day ends?"}
C -- "No" --> D["Cancel step 2, switch off, investigate"]
C -- "Yes" --> E["Step 2 applies as planned"]
E --> F["Schedule step 3 for the next day, 25 percent"]
F --> G{"Healthy again?"}
G -- "No" --> D
G -- "Yes" --> H["Continue, scheduling only one step ahead"]
The figure shows the principle. After step one is live, only step two is scheduled, for the next day. At the end of that day the team asks whether things are healthy. A no cancels the pending step and switches the feature off for investigation. A yes lets step two apply, and only then is step three scheduled. At no time is the calendar more than one step ahead of the evidence.
A hiker crossing a glacier does not book the full route to the summit for a fixed hour each day. She plans the next stage, checks the weather and the ice at the end of the day, and only then plans the one after. A schedule that ignores conditions is a promise made without information, and mountains punish those.
| Approach | Strength | Weakness | Verdict |
|---|---|---|---|
| Raise by hand at each step | Full control and attention | Needs a person at each step, easy to forget | Fine for small teams |
| Schedule the whole ramp now | Visible and hands-free | Ignores bad news, keeps widening | Risky, avoid for risky features |
| Schedule one step ahead | Hands-free with a built-in check | Needs a daily look at the results | Best balance for most teams |
| Automate with metrics gates | Fully automatic and safe | Needs real engineering work | For mature teams, see Chapter 22 |
Real-world example: automated canary analysis
Netflix has publicly described automated analysis that compares a small new group against an unchanged group and decides whether a release should continue, instead of following a fixed timetable. Scheduled ramps with a health check before each next step are the human-sized version of that idea.
Whenever you schedule a widening, put the guardrail thresholds in the change’s description: “cancel if error rate exceeds 1.5 percent”. The next person to see it, possibly at night, will know exactly when to stop it.
16Pattern: Regional and Time-Zone Launches
A single global instant is not always the right moment. Sometimes “midnight” should arrive separately in each place.
One instant or many local moments?
A scheduled change is applied at one instant, shared by everyone. That suits announcements pegged to a global event. But some launches are about local time: a sale that starts at midnight wherever the customer lives, or a morning-only offer. A single instant cannot be midnight everywhere. The solution is to schedule several changes, one for each region, and to use segments so each change reaches only the people in that region.
flowchart LR
S["Region segments: Asia, Europe, Americas"] --> W1["Wave 1: 00:00 local in Asia"]
S --> W2["Wave 2: 00:00 local in Europe"]
S --> W3["Wave 3: 00:00 local in Americas"]
W1 --> V1["Verify wave 1, guardrails calm"]
V1 --> W2
W2 --> V2["Verify wave 2, guardrails calm"]
V2 --> W3
The figure shows three region segments feeding three waves. The first wave applies at midnight local time in Asia, the second at midnight in Europe and the third at midnight in the Americas. Between waves the team verifies that the guardrails are calm before the next region begins. This turns one risky global moment into three smaller, local ones, each watched by the team before the next.
The benefits of waves
Smaller blast radius
A fault in the first wave harms one region’s customers, not all of them.
Learning in sequence
Lessons from the first wave improve the second and third.
Friendly hours
Support teams in each region are awake and ready at their own local launch.
Spread load
Traffic peaks arrive at different hours instead of all at once.
The costs of waves
Waves are more work. You need region segments, which rely on a trait such as country or region being sent reliably by your applications. You need more scheduled changes, each with its own approval and its own time-zone arithmetic. And the customer experience is uneven: a friend in another country may see the sale hours after you, which can cause confusion on social media. Weigh these costs against the risk reduction, and choose deliberately.
New Year’s Eve celebrations roll around the world, one time zone after another, each with its own midnight. Nobody expects the whole planet to cheer at one instant. A global product launch with a local feel behaves the same way, and the rolling pattern gives the organisers time to adjust as it moves.
| Choice | Good for | Needs | Risk |
|---|---|---|---|
| One global instant | Announcements tied to a global event | One scheduled change | All customers share any fault together |
| Regional waves, local midnight | Sales and offers tied to local days | Region segments and several changes | Uneven experience across regions |
| Regional waves, same instant, sequenced by risk | Cautious global launches | Region segments and checks between waves | Some regions wait longer |
Region segments are only as good as the traits that feed them. If some customers have no country trait, they match no region and receive nothing at any wave. Test with identities that have missing and mixed-up traits before launch night.
17Load, Crowds and the Thundering Herd
When a scheduled change turns something on for everyone at once, the crowd arrives together. The system must be ready for that crowd.
The thundering herd
The thundering herd is a name for the surge that follows a shared trigger. Thousands of people have been waiting for the sale, and the moment the banner appears they all click through together. Requests that were spread across the day arrive in the same minute. Even if the flag change itself is tiny, its effect on your traffic can be enormous.
The arithmetic of a spike
Suppose a typical evening sees two hundred requests per second to the sale page, and a promotion tied to a launch at midnight brings ten times that. At the launch minute you must handle two thousand requests per second. If each request reads a handful of flags and touches a database, the extra pressure falls on every layer behind the page. A scheduled flag change does not create this load, but it chooses the exact minute when the load arrives.
Ways to soften the spike
Warm things up early
Reveal the feature to a small group an hour earlier, so caches, connections and databases have already met the new path.
Stagger the audience
Instead of one switch for all, schedule two or three steps a few minutes apart, such as one quarter, one half, then everyone.
Use region waves
Different regions arrive at different hours, naturally spreading the load.
Test at launch-sized load
Run a load test in a safe environment at the expected crowd size before the real moment.
Keep a quick way out
Know in advance how to switch the feature off, and how long that takes to reach users.
A stadium does not open all its gates and all its turnstiles at the same instant for a hundred thousand people. It opens the doors early, directs people by section and keeps staff at the busiest gates. The match starts at one moment, but the crowd is eased in over an hour. A scheduled launch deserves the same easing.
Real-world example: planning for the sale-day spike
Large retailers, including Amazon, have publicly described preparing infrastructure for sale-day peaks well in advance, including load testing and capacity reservations. The flag change at the start of a sale is the smallest and quietest part of the plan. The heavy preparation is everything that must survive the crowd it invites.
When planning a launch, ask your infrastructure colleagues one question: “If every interested customer arrives within five minutes of go-live, what breaks first?” Fix that, and the flag change will look easy.
18Testing Scheduled Changes Before the Real Moment
A scheduled change is a plan that runs without you. Plans that run without you deserve a rehearsal.
Rehearse in a safe environment
The cheapest, most valuable test is a rehearsal. In Staging, schedule a harmless change a few minutes into the future, then watch. Does it appear in the pending list with the time you meant? Does it apply at the right moment? Does it appear in the audit log? Do your apps show the new state, and after how long? A ten-minute rehearsal on a quiet afternoon teaches more than an hour of reading documentation.
What to rehearse
| Test | How | What you learn |
|---|---|---|
| Basic timing | Schedule a change five minutes ahead | Whether it applies when you expect |
| Time zone handling | Check the time shown by two people in different zones | Whether everyone reads the same instant |
| Propagation delay | Time how long each app takes to show the change | Your real lead time |
| Approval flow | Submit, approve late, approve early | How your version treats each case |
| Cancellation | Cancel a pending change a minute before its time | Whether the cancellation is clean |
| Combined state | Schedule a value and a segment override together | Whether all pieces apply together |
| Worker health | Self-hosted: stop the worker briefly and restart | How missed changes recover |
Test identities for before and after
Keep a few permanent test identities for the audience of your launch: one inside the audience, one outside, one at the edge. Before the go-live time, confirm each sees the old behaviour. After it, confirm each sees the new. Doing this against Production on launch day, using test accounts that do not affect real customers, is the final proof that the plan worked.
A fire drill is a rehearsal for something everyone hopes never happens. Nobody enjoys it, and everyone is glad of it when the alarm rings for real, because they know where the exits are. A rehearsed scheduled change turns launch night into a well-practised routine instead of an adventure.
A rehearsal checklist
Create a harmless flag
Use a flag that changes nothing important, such as a small label in a test page.
Schedule it a few minutes ahead
Write down the exact intended instant in two time zones.
Watch the clock
Note when the change applies in the audit log and when your test page shows it.
Record the results
Write down the delay you measured and keep it with the launch runbook.
Repeat after major changes
Rehearse again after upgrades, migrations or a change of caching settings.
Do not rehearse in Production with real flags. Use a test environment or a harmless flag. A rehearsal that accidentally launches a feature is the quickest way to turn practice into an incident.
19Watching the Moment: Monitoring and Verification
A scheduled change removes the work before the moment, not the need to look afterwards. Someone should always watch what happens next.
What to confirm at T zero
Three questions matter in the first minutes after a go-live time. Did the change apply, meaning does the flag show the new state and does the audit log record it? Do users see it, meaning do your test identities and your own apps reflect the new state? And is everything healthy, meaning are errors, speed and business numbers steady? The first is Flagsmith’s job, the second the SDKs’ and caches’, the third your whole system’s.
Where to look
Audit log
Confirms that the change applied, the time it happened and what changed. The first stop for “did it fire”.
Webhooks and chat alerts
Send applied changes to your team channel, so everyone sees the moment without opening the dashboard.
Test identities
Confirm that users in the audience see the new state, and others do not.
Guardrail dashboards
Watch errors, speed and conversion for the people with the feature versus those without.
Mark the moment on your charts
A graph that dips at 00:03 means little without context. A vertical line labelled “sale banner enabled 23:58 IST” turns confusion into a clear before and after. Where your monitoring tool supports annotations, create one automatically from the webhook that Flagsmith sends when a change applies. Future reviewers, including yourself next month, will be grateful.
A chef who puts a cake in the oven on a timer does not leave the building. She sets an alarm, comes back when it rings and checks that the cake is cooked. The timer did the waiting. The chef still does the judging. A scheduled change plays the role of the timer, and your team plays the role of the chef.
A short verification routine
At T zero: read the audit log
Confirm the entry exists with the expected time, flag and environment.
At T plus 5 minutes: check test identities
Use accounts in and out of the audience to confirm the new state is visible.
At T plus 15 minutes: read the guardrails
Errors, response times and key conversion numbers against the baseline.
At T plus 1 hour: confirm the plan is stable
Check support channels, customer messages and load on dependencies.
At T plus 1 day: review and clean up
Note what went well and what surprised you, and remove anything temporary.
Real-world example: annotating changes on timelines
Engineering teams at companies such as Etsy have publicly described marking deployments and configuration changes on their monitoring graphs, so that any sudden movement can be matched to its cause at a glance. Applying the same habit to scheduled flag changes makes post-launch analysis far quicker.
Assign one person to watch the first fifteen minutes with no other job. Their only task is to say “healthy” or “not healthy” aloud. A single named watcher is faster than a crowd who each assume someone else is looking.
20Cancelling, Rescheduling and Rolling Back
Plans change. The right response depends on whether the change has already happened.
flowchart TD
A["Plan needs to change"] --> B{"Has the change applied yet?"}
B -- "No" --> C{"Time or content wrong?"}
C -- "Time" --> D["Reschedule: edit the go-live time"]
C -- "Content" --> E["Edit the pending change, re-approve if needed"]
C -- "Whole plan wrong" --> F["Cancel the pending change"]
B -- "Yes" --> G{"Is it causing harm?"}
G -- "Yes" --> H["Switch the flag or override off now"]
G -- "No" --> I["Make a new change to the desired state"]
H --> J["Investigate, fix, then plan a new schedule"]
The figure begins with a plan that needs to change and splits on one question: has the change applied yet? If not, there are three gentle options. A wrong time is rescheduled by editing the go-live time. Wrong content is fixed by editing the pending change, which may need to be approved again. A plan that is wrong as a whole is cancelled. If the change has already applied, you cannot cancel it. If it is causing harm, you switch the flag off immediately. If not, you make a new change to reach the state you want.
Rescheduling safely
Moving a go-live time is a change like any other, and it deserves the same checks. Confirm the new time in two time zones. Check whether editing the time clears the approval, which in some setups it does. Tell the people who were counting on the old time, including support, marketing and on-call staff. A rescheduled launch that nobody remembers rescheduling is a recipe for confusion.
Rolling back an applied change
Rolling back means returning to the previous state. With plain flags, that is a manual change or a new scheduled change that restores the old state. With feature versioning, you may be able to restore an earlier version quickly. Whichever way, the rollback takes effect on the same schedule as any other change: after the worker applies it and caches refresh. Practise it, and know how long it takes, before you need it under pressure.
A booked train ticket can be changed or refunded before departure, with little fuss. After the train has left, you cannot cancel the trip, you can only buy a ticket back. Treat scheduled changes in the same way: freely adjustable until they happen, and after that, undone only by a new action.
| Need | Right action | Speed | Watch for |
|---|---|---|---|
| Wrong time, not yet applied | Edit the go-live time | Immediate | Approval may reset |
| Wrong value, not yet applied | Edit the pending change | Immediate | Re-review needed |
| Plan abandoned | Cancel the pending change | Immediate | Tell the team it was cancelled |
| Applied and harmful | Switch off the flag | Worker plus cache delay | Confirm no other pending change turns it back on |
| Applied, wrong but harmless | New scheduled change to the right state | As scheduled | Check the state in between |
After switching a flag off in an emergency, always check the pending list. A forgotten scheduled change that enables the same flag will undo your safety action at its time, usually when nobody is watching.
21Debugging: It Didn’t Fire, It Fired Late, It Fired Wrong
Sooner or later a scheduled change will not behave as planned. An ordered method finds the cause quickly, most of the time in the first two checks.
flowchart TD
A["Report: scheduled change did not show"] --> B{"In the audit log as applied?"}
B -- "No" --> C{"Still in the pending list?"}
C -- "Yes, time is future" --> C1["Time zone or date was wrong, fix the time"]
C -- "Yes, time is past" --> C2["Not approved, or worker not running"]
C -- "No" --> C3["It was cancelled or replaced, check history"]
B -- "Yes" --> D{"Right environment and flag?"}
D -- "No" --> D1["Schedule was on the wrong environment"]
D -- "Yes" --> E{"Later change overwrote it?"}
E -- "Yes" --> E1["Check the order of changes and manual edits"]
E -- "No" --> F{"Cache or refresh delay?"}
F -- "Yes" --> F1["Wait one refresh period and retest"]
F -- "No" --> G["Check the identity, traits and segment rules"]
The figure starts with the most useful question: does the audit log show the change as applied? If not, the change either never applied or never existed. Look in the pending list. A change still pending with a future time usually means the time or zone was wrong. A change still pending with a past time points to a missing approval or a worker that is not running. If the change is no longer pending, it was cancelled or replaced. If the log says applied, check that the environment and flag were right, whether a later change or manual edit overwrote it, and whether caches simply need time. Only then look at segments and identities.
Common symptoms and likely causes
| Symptom | Likely cause | First check |
|---|---|---|
| Nothing happened at the time | Not approved, worker stopped or wrong time zone | Pending list status and the displayed zone |
| It happened hours early or late | Time zone confusion | The instant in UTC against the plan |
| It happened but users do not see it | Caches or an old app version | Test identities and cache settings |
| It happened, then reversed | A later scheduled or manual change | Audit log between applying and reversing |
| Wrong value appeared | Snapshot was older than a manual edit | Value history and the order of edits |
| Applied in Staging, not in Production | Scheduled on the wrong environment | Environment name on the pending change |
| Some users see it, others do not | Segment rules, percentage split or mixed period | Audience rules and refresh timing |
| Self-hosted: nothing ever fires | Worker not running | Worker process and its logs |
When a package fails to arrive, you check the tracking page first: was it dispatched, and where is it? Only then do you phone the courier or the neighbours. The audit log is the tracking page of a scheduled change. It tells you in seconds whether the parcel ever left the depot.
Keep a short “scheduled change troubleshooting” page in your team’s notes, with the diagram above and the names of the people who can restart the worker or approve changes. It turns a midnight panic into a ten-minute routine.
22Automating Schedules with the API, Terraform and Calendars
When changes are many, repeated or tied to other systems, a person clicking dates in a dashboard stops being the safest approach.
The Admin API
An API, short for application programming interface, is a doorway that lets one program talk to another with agreed rules. Flagsmith’s Admin API is the doorway for management tasks, such as reading a flag’s state, creating a change request or updating a value. A script can use it to create scheduled changes in bulk, to read the pending list and compare it with a plan, or to apply a change at a moment decided by your own systems. A secure token proves the script has permission, and that token must be guarded like a password.
Infrastructure as code and Terraform
Infrastructure as code means describing systems in text files that are stored, reviewed and versioned like software. Terraform is a widely used tool for this, and a provider exists for Flagsmith, so flags and their configuration can be written in files and applied automatically. Terraform describes desired states more than timed events, so it fits best for the flag definitions and the environments, with the scheduling itself handled by the dashboard or the API. Check the current provider documentation to see what it supports in your version.
Your own scheduler
If your plan does not include native scheduling, or if you need logic that the native feature does not offer, you can build a small scheduler of your own. A job runner, such as a cron job or a pipeline’s scheduled run, calls the Admin API at the chosen time to change the flag. This works, but you now own its reliability. The job must run on time, retry on failure, alert when it fails and avoid applying twice. The honest comparison is that native scheduling gives you a managed, audited feature, and a custom job gives you flexibility at the cost of care.
flowchart LR
CAL["Launch calendar or ticket"] --> PL["Pipeline reads the plan"]
PL --> CK["Checks: approvals, test results, time"]
CK --> API["Calls Flagsmith Admin API"]
API --> SCH["Creates or updates the scheduled change"]
SCH --> LOG["Audit log and chat alert"]
LOG --> WATCH["Team verifies at T zero"]
The figure shows a launch plan, kept in a calendar or ticket, read by a pipeline. The pipeline checks the plan: are approvals in place, have tests passed, is the time sensible? Only then does it call the Admin API to create or update the scheduled change. The audit log and a chat alert record it, and the team verifies at T zero. The value of the design is that the checks happen in code, the same way every time, and the humans only need to look at the result.
Dashboard scheduling
Managed, audited and simple. Limited to what the feature supports. Best for most teams.
Scripts and pipelines
Flexible, repeatable and connected to other systems. You own the reliability.
Flag definitions as code
Strong for structure and consistency. Less suited to timed events.
Your own job runner
Maximum freedom. Needs retries, alerts and protection against double application.
A household can set the heating timer on the thermostat, which is simple and built in. A keen engineer can instead wire up a custom controller that reads the weather and the family calendar. The second is more powerful and needs more care, and when it breaks on a freezing night, nobody can blame the manual. Choose the lighter tool unless the extra power is truly needed.
Automation should read first and write second, and it should never write to Production without the same approval your humans need. A script that can change Production flags unreviewed is a very fast way to make a very large mistake.
23Governance: Who May Schedule What, and When
A scheduled change can alter what customers see while everyone is asleep. That power deserves clear rules about who holds it.
What is governance?
Governance is a set of agreed rules about who may do what, and a way of checking that the rules are followed. For scheduled changes, it answers practical questions. Who may create a change in Production? Who must approve it? How far ahead may changes be scheduled? Which days and hours are off-limits? Who holds the authority to cancel a change that looks wrong? A small team can answer these in a shared note. A large organisation may use roles, reviews and regular audits.
Permissions
| Activity | Typical people | Why limit it |
|---|---|---|
| View pending changes | Everyone on the project | Transparency lets people spot conflicts early |
| Schedule in Development and Staging | Any developer | Low risk, high value for rehearsal |
| Schedule in Production | Release owners | The change reaches real customers |
| Approve Production changes | Named reviewers, not the author | A second pair of eyes catches mistakes |
| Cancel Production changes | Owners and on-call staff | Emergency authority, reviewed afterwards |
Change freezes
A change freeze is a period when non-urgent changes are not allowed, such as the days around a major sale, the end of a financial quarter or a holiday when few engineers are available. Scheduled changes interact with freezes in a subtle way: a change prepared before the freeze but due during it will still apply, because the system does not know about your calendar. Review the pending list at the start of every freeze, and cancel or move anything that would land inside it without a deliberate decision.
A building has a rule that no loud construction takes place at night. A contractor who booked a drilling job last month still shows up at midnight on the day, unless somebody remembers to cancel it. The rule is only as good as the check that compares the booked jobs with the quiet hours.
A calendar everyone can see
One shared launch calendar
List every scheduled change in Production, with the time, owner and rollback, in a place the whole team reads.
A weekly pending-list review
Ten minutes on Monday looking at what is due this week catches forgotten and conflicting plans.
Named owners on every change
Each pending change has a person who answers for it, written in its description.
Review after each launch
Ten minutes on what went well and what surprised you improves the next one.
Real-world example: freezes and calendars in large organisations
Many large retailers and financial firms have publicly described change freezes around peak trading periods, with strict controls over what may be altered. Treating scheduled flag changes as part of the same calendar, not as a loophole around it, keeps those freezes meaningful.
Make the launch calendar the single place where “what is going to change, and when” is written. If a change is scheduled in Flagsmith but missing from the calendar, treat it as a mistake until proved otherwise.
24Security, Privacy and Compliance
Timing can be a security matter too. A flag that turns on early, or stays on late, is sometimes more than an embarrassment.
Embargoes and early exposure
Some information may not become public before a certain moment, such as unreleased prices, financial results or partner announcements. Scheduling the flag that reveals it is a natural fit, but the schedule alone is not a lock. Lead time, caches and mixed periods can expose content slightly early, and any value delivered to a client app can be seen by a determined person. For anything that must remain secret until a moment, keep the content itself on the server and release it by a server-side check at the right time, using the flag only to control the presentation.
Time-limited access
Temporary access, such as a feature for a partner during a trial, is sometimes managed with flags. Scheduling its end avoids the quiet risk of a trial that never expires. But a flag is a presentation switch, not an access control. Use real permissions on your server for anything that must truly stop, and let the flag reflect the same decision in the interface.
Compliance and records
Regulated industries often need to show who changed what and when. The audit log helps, and scheduled changes add two moments to record: when the change was prepared and approved, and when it applied. Keep both, and keep the reasons. A change description that says “approved by Priya for the announced offer, per ticket 4821” is worth more to an auditor than any number of silent clicks.
| Concern | Risk with scheduling | Safer practice |
|---|---|---|
| Embargoed content | Early visibility from lead time and caches | Keep content server-side, release by server check |
| Secrets in values | Visible to client apps even briefly | Never store secrets in flag values |
| Trial and access ends | Flag off but access still open on the server | Enforce on the server, flag follows |
| Unreviewed Production changes | Scheduled by one person with no approval | Require approval for Production |
| Stolen API token | Attacker schedules harmful changes | Scope, rotate and monitor tokens |
| Missing records | No evidence of who planned what | Descriptions and tickets on every change |
A newspaper embargo says a story must not appear before a stated hour. The paper does not put the story on the front page and cover it with a sticker until the hour. It keeps the story locked until the moment and prints it then. A flag that hides content already sent to the user’s device is the sticker, not the lock.
Good practice
- Keep embargoed content on the server
- Require approval for Production schedules
- Scope and rotate Admin API tokens
- Record reasons and ticket numbers on each change
Risky practice
- Relying on a timed flag to hide secrets
- Letting one person schedule and apply alone
- Long-lived, unscoped API tokens in scripts
- No record of why a change was planned
Laws and contracts about disclosure, personal data and financial reporting differ between countries and change over time. Treat this chapter as general good practice and consult your legal and compliance teams about the rules that apply to you.
25Anti-patterns to Avoid
An anti-pattern is a habit that looks reasonable and causes trouble later. These five are the most common with scheduled changes.
What it looks like
A change is scheduled, the team goes home and nobody confirms it was approved, correctly timed or even created in the right environment.
Why it hurts
If anything is wrong, nobody notices until customers do. The change may never fire, may fire at the wrong hour or may fire on Staging.
Do this instead
Check the pending list the day before, name a watcher for T zero and verify with test identities afterwards.
What it looks like
The flag is scheduled for the launch hour, but the build containing the feature is still going through release testing.
Why it hurts
At go-live, the flag turns on and nothing appears, or an old build reacts strangely. A launch is lost to a scheduling mistake.
Do this instead
Deploy the code days earlier with the flag off, verify it, and let the schedule release it.
What it looks like
A dozen changes are scheduled weeks ahead for one flag, including a full percentage ramp, none of which anyone reviews again.
Why it hurts
Conditions change, but the calendar does not. The ramp widens even when problems appear, and manual edits are overwritten by old snapshots.
Do this instead
Schedule one or two steps ahead, and extend the calendar only as each step proves healthy.
What it looks like
The plan says “midnight on the 15th” with no zone, no year and no clarification of start or end of the day.
Why it hurts
Different people read different moments. The change lands hours or a day away from the public promise.
Do this instead
State the moment in UTC and local time, with the full date, and have a second person check it.
What it looks like
During an incident someone switches a flag off by hand. An old scheduled change, prepared before the incident, turns it back on hours later.
Why it hurts
The incident returns while the team sleeps, and the cause is hard to see because the change was invisible in the day’s discussion.
Do this instead
Make “check and cancel pending changes on this flag” part of every incident runbook.
Real-world example: learning from configuration incidents
Large technology companies have publicly shared post-incident reviews in which a configuration change, applied at an unexpected time or in an unexpected order, was part of the cause. The recurring lesson is that timed changes must be as visible and as reviewed as code, because they are changes to behaviour, whatever their name.
26Advantages, Disadvantages and Trade-offs
Scheduled flag changes are a strong, simple tool with real limits. Seeing both sides helps you use them where they pay.
Advantages
- Preparation moves to calm daylight, away from the stressful moment
- The change applied is exactly the one reviewed and approved
- No deployment and no person needed at the go-live time
- Teams in different time zones can plan one shared moment
- Clear audit trail of the plan and of its application
- Endings, such as sales and maintenance windows, are never forgotten
Disadvantages
- Applied is not seen: caches add a delay and a mixed period
- Timing is within about a minute, not exact to the second
- Time zone mistakes are easy and costly
- Pending changes can overwrite later manual edits
- A missing approval or a stopped worker fails silently
- May need a paid plan or extra setup when self-hosted
Scheduling compared with other ways of timing a change
| Method | Strength | Weakness | Best for |
|---|---|---|---|
| Native scheduled flag change | Managed, audited and simple | Limited to what the feature supports | Most timed launches and shutdowns |
| Manual change at the moment | Full attention and judgement | Human nerves and time zones | Surprises you could not plan |
| Custom job calling the API | Flexible and connected to other systems | You own reliability and alerts | Complex, repeated or data-driven timing |
| Date check in your own code | Exact and independent of Flagsmith | Needs a deployment to change, hides logic in code | Rare fixed dates that never move |
| Client device clock | Works offline | Users can change the clock, devices disagree | Cosmetic effects only |
A hotel can wake guests with a call from the front desk, an alarm clock in the room or a note pushed under the door. The front desk is reliable but needs a person. The alarm is under the guest’s control, and might be set wrong. The note arrives only if someone remembers. Each is right in its own place. Scheduled flag changes are the front-desk call that the system makes for you.
When not to schedule
Second-exact moments
If fairness depends on the exact second, add a queue or waiting room. A flag alone is not precise enough.
Unclear plans
If nobody knows what should happen, scheduling hides the confusion instead of solving it.
Security boundaries
Timed flags are presentation switches. Access must be enforced on the server.
Unsafe features
A feature that is not ready is not made ready by putting it on a timer.
If a plan needs the exact second, the exact order across many flags, and a crowd that cannot be absorbed, scheduling a flag is only the final, smallest piece. Spend your design effort on the larger system around it.
27Best Practices and Common Mistakes
Experienced teams repeat a short list of habits. Newer teams repeat a short list of mistakes. Here are both.
Habits worth building
Write the plan as a countdown
A T-minus document that everyone can read, from planning to clean-up, turns a launch into a routine.
State times in two zones
UTC and the local clock, with the full date, in the change’s description and in announcements.
Deploy code first, release by schedule
The risky act early, the safe act at the moment that matters.
Add lead time for caches
Apply a few minutes before the public moment, by more than your slowest cache.
Get approval early and confirm it landed
Submit a day ahead and check the state is “approved and scheduled” the day before.
Rehearse in Staging
A five-minute schedule on a harmless flag teaches your real timing and delay.
Name a watcher for T zero
One person whose only job is to say “healthy” or “not healthy” for the first fifteen minutes.
Schedule the end with the beginning
Promotions, trials and maintenance windows should have their endings planned at the same sitting.
Mistakes to catch early
Wrong environment
The change is scheduled on Staging, and Production never changes. Check the environment name on the pending item.
Wrong time zone
A launch lands hours early or late because the picker used a different zone from the one intended.
No approval
A scheduled change that was never approved quietly does not apply, or applies late.
Forgetting the cache
The audit log says applied, users still see the old state, and panic follows.
Overwriting a manual fix
An old scheduled snapshot replaces a hand edit made during an incident.
Assuming simultaneous flags
Several flags scheduled for the same minute are applied one after another, not together.
Print the habits and mistakes lists and pin them beside your launch checklist. Short, visible reminders work better than long documents nobody reopens.
28A Complete Worked Scenario
To finish, here is one imaginary launch taken from planning to clean-up, using everything in this guide.
BrightCart, the imaginary online shop, has promised a festive-season sale that begins at midnight India time on the fifteenth of the month and ends at 23:59 on the twentieth. The sale needs three things to change: a banner flag, a flag that switches the new discount calculation on and a remote value holding the banner text. The code was written weeks ago. Customers are mostly in India, with a smaller number overseas. A self-hosted Flagsmith installation serves all flags.
One week before: write the countdown
The release owner writes a T-minus document naming owners, the exact moments in IST and UTC, the rollback and the people who must be awake. The sale start is 00:00 IST on the fifteenth, which is 18:30 UTC on the fourteenth. The end is 23:59 IST on the twentieth.
Five days before: deploy the code
The new build, containing both the banner and the discount logic, goes live in Production with both flags off. A day of normal traffic confirms the deployment itself is healthy.
Four days before: rehearse and measure
In Staging, a harmless change is scheduled five minutes ahead. The audit log shows it applied within a minute. The web app shows it after about two minutes, the mobile app after about eight. The team notes these delays. The self-hosted worker is confirmed healthy, and an alarm for its failure is tested.
Three days before: choose the plan
With the slowest cache at eight minutes, the team adds fifteen minutes of lead time, so the banner and discount flags are scheduled for 23:45 IST on the fourteenth. To avoid a spike at the exact minute, the discount flag is scheduled in two steps, a percentage of customers at 23:45 and all customers at 23:58, with a segment for staff enabled two days earlier.
Two days before: staff preview
A scheduled change turns the banner and discount on for the staff segment. Employees test with real accounts and refund their own orders. One text error in the banner is found and fixed in the pending change.
One day before: approve and freeze
A colleague reviews every pending change, including the zone shown and the end-of-sale disable at 23:59 on the twentieth. All are marked approved. Other edits to these flags are frozen, and the pending list is posted in the launch channel.
Launch night: watch, do not click
At 23:40 the team opens dashboards. At 23:45 the first step applies and the audit log shows it. Test identities see the new state within ten minutes. At 23:58 the second step applies. Traffic rises to about nine times the evening norm and guardrails stay calm.
During the sale: a small surprise
On the third day, a partner payment service has a short fault. The on-call engineer switches the discount flag off by hand, then checks the pending list and finds nothing pending that would turn it back on. When the partner recovers, a new change restores the flag.
The end of the sale
At 23:59 on the twentieth the scheduled disable applies. The banner disappears, the discount logic switches off and the banner text returns to its normal value. A watcher confirms with test identities and the audit log.
The day after: review and clean up
The team reviews the timings, notes that mobile delay was close to the lead time and decides to add five more minutes next time. The sale-specific flags and segments are removed, and the countdown document is kept as a template.
Look at step eight. The on-call engineer did two things: switched off the flag and checked the pending list. The second action is the one people forget, and it is what prevents a forgotten scheduled change from undoing the fix.
What would have gone wrong without the routine?
Suppose the team had scheduled exactly at midnight with no lead time. Mobile customers, who see changes about eight minutes late, would have missed the first eight minutes of the sale, and many would have blamed the shop. Suppose they had typed 00:00 in a laptop set to UTC. The sale would have started five and a half hours late, at 05:30 IST. Suppose they had not rehearsed with the self-hosted worker. A silent worker failure would have meant that nothing happened at all, with no one awake. Each of these is an ordinary mistake, and each is caught by the habits in this guide.
29Frequently Asked Questions
Short, direct answers to the questions people ask most often about scheduled flag changes.
30Summary and Key Takeaways
Scheduled flag changes move the hard work of a release to a calm hour, and let the system do the exact thing at the exact time. A few ideas carry nearly all of the value.
Key Takeaways
- A schedule is a prepared target state. Flagsmith’s servers apply it once, for everyone, at the chosen time. Device clocks play no part, and the code must already be deployed.
- Applied is not seen. A background worker applies changes within about a minute, and caches add a further delay, so add lead time and measure your own numbers.
- Time zones cause most failures. State every moment in UTC and local time with the full date, have a second person check the zone and rehearse in Staging.
- Approval and schedule are separate safeguards. Submit early, confirm “approved and scheduled” the day before and learn how your version treats late approval.
- Schedule short, not long. Prefer one or two steps ahead, check the pending list before any manual edit and cancel forgotten changes after any incident.
- Plan the crowd, not just the switch. Warm up early, stagger the audience, use regional waves where local midnight matters and keep a quick way out.
- Watch, verify and clean up. Name a watcher for T zero, use the audit log and test identities, annotate your charts and remove temporary flags afterwards.