Three short definitions come first: the feature flag, the boolean, and the platform that holds them.

The feature flag

A feature flag (also called a feature toggle or feature switch) is a control placed inside software that decides whether a certain behaviour is active. The code is already deployed on the servers. The flag decides whether users can reach it. Change the flag and the behaviour changes, with no new release.

The boolean

A boolean is a value with exactly two possible states: true or false, on or off, yes or no. A boolean feature flag is therefore a flag with exactly two answers. When the application asks “should I show this feature?”, the reply is either yes or no. There is no “maybe” and no “ten out of twenty”. That narrowness is its strength, because a two state switch is easy to understand, easy to test and easy to reverse.

The platform

Flagsmith is a feature flag and remote configuration service. It provides a dashboard where people manage flags, and small libraries called SDKs that applications install so they can ask, “what is this flag right now?” It is open source, can be hosted by a company itself, and is also offered as a hosted service.

Many people assume serious engineering needs complex controls. In practice, a plain true or false solves most real problems.

The problem it solves

Before flags, releasing a feature meant deploying new code, and deploying meant risk. If something broke, the only remedy was another deployment to undo the first, which could take an hour while customers suffered. Boolean flags separate two things that used to be glued together: deployment, which is putting code on servers, and release, which is letting users see it. Deployment can happen quietly on a Tuesday. Release happens when the business is ready, at the click of a switch.

What large companies teach us

Engineering organisations known for frequent releases, such as Amazon, Netflix, Etsy and Facebook, have described in public talks and articles the idea of hiding unfinished work behind switches so that code can be merged and shipped many times a day. Etsy’s writing about “config flags” is a well known example. The reasoning is the same at any size. A plain on and off switch is quick to build, quick to understand and quick to reverse, which is exactly what you want when something might go wrong.

What a boolean flag cannot do

It helps to know the limits. A boolean flag cannot tell you how much of something to show, only whether to show it. It cannot choose between three versions of a page. It cannot carry a message or a number. When you need those, Flagsmith offers values and multivariate features. The sensible habit is to begin with the simplest tool that solves the problem, and to reach for a richer one only when the plain switch genuinely is not enough.

Open any flag in Flagsmith and you will find the same handful of parts. Knowing them makes the dashboard feel familiar.

The two layers: definition and state

A flag has two layers that beginners often confuse. The definition is the existence of the flag: its name, description and tags. It lives at the Project level and is shared by every Environment. The state is whether it is enabled in a particular Environment. It lives inside that Environment. So the flag “checkout_new_payment_sheet” exists once in the Project, yet it can be enabled in Development, enabled for testers in Staging, and disabled in Production, all at the same moment.

What you see at a glance

In the dashboard’s feature list, each row typically shows the flag name, its tags, a switch for the current Environment and a short summary of any overrides. A quick scan tells you which flags are on, which are off, and which have special rules for certain groups. Learn to read that list the way a pilot reads a cockpit panel: the important facts are visible without opening anything. If you ever have to open five screens to understand one flag, the flag has probably been set up in a confusing way.

Flagsmith offers more than on and off. Seeing the neighbours helps you decide when plain boolean is the right choice.

The three kinds of feature

The boolean flag answers a yes or no question. Remote configuration hands the application a value, such as a number, a piece of text or a limit, that can be changed live without a release. A multivariate feature offers several values and splits users between them by percentage, which is the base of experiments.

A confusing detail: enabled state versus value

In Flagsmith, a single feature can carry both an enabled state and a value. The enabled state is the on and off switch. The value is an optional extra piece of information. A value may itself be the text “true” or “false”, or a true or false type, and that is not the same as the enabled state. Mixing these up causes real bugs. A flag may be enabled with a value of false, which the code must read as “feature on, setting off”. As a rule, keep a boolean flag pure: use the enabled state for the yes or no question and leave the value empty. If you need a setting as well, use a separate remote configuration feature with its own name.

Flagsmith is organised as a tree. Locating the flag in that tree explains who can change it and where its answer is stored.

At the top is the Organisation, which holds people, groups and billing. Beneath it are Projects, one for each product. Inside each Project the features are defined, and beneath each Project are Environments such as Development and Production. The enabled or disabled state of each flag is stored in each Environment.

graph TD
  ORG["Organisation: Acme Corp"] --> PRJ["Project: Store"]
  PRJ --> FEAT["Feature definition: checkout_new_payment_sheet"]
  PRJ --> DEV["Environment: Development"]
  PRJ --> STG["Environment: Staging"]
  PRJ --> PRD["Environment: Production"]
  DEV --> S1["State: Enabled"]
  STG --> S2["State: Enabled for testers"]
  PRD --> S3["State: Disabled"]
  FEAT -.-> S1
  FEAT -.-> S2
  FEAT -.-> S3
    

What this means in practice

Because the state belongs to the Environment, you can safely turn a flag on in Development without affecting customers. Because the definition belongs to the Project, your code can ask for the flag by name in any stage and always get an answer. And because the Organisation sits above, it decides which people are allowed to flip the flag in each place.

Creating a flag takes a minute. Creating a flag well takes a minute and a half, and the extra thirty seconds saves hours later.

Questions people ask at creation time

Should the flag start on or off? Off, almost always. A new flag that starts on can change what customers see the moment it is created, which defeats its purpose. Should I create it in code first or in Flagsmith first? Create it in Flagsmith first, disabled, then write the code. That way the code can be deployed safely at any time, because asking for a flag that exists and is off simply returns the old behaviour. Should several features share one flag? Rarely. One flag per behaviour keeps testing and reversal simple. If two features must move together, give them one flag on purpose and say so in the description.

A flag in a dashboard does nothing until an application asks about it. This chapter explains that conversation in plain language.

The SDK

An SDK (software development kit) is a ready made library that your application installs so it can talk to Flagsmith without you writing the network code. Flagsmith provides SDKs for many languages, for websites, for mobile apps and for servers. Each SDK offers a very simple question for boolean flags, which can be read aloud as “is this feature enabled?” The answer is true or false.

The Environment key

To know which Environment to ask, the SDK holds an Environment key, a string that identifies the stage. Development builds use the Development key, and the live product uses the Production key. This is why a test build can never accidentally read live values.

The shape of the check

In the application, the idea is always the same. The code asks whether the flag is enabled. If yes, it runs the new behaviour. If no, it runs the old behaviour. Both paths exist in the code at the same time, which is what lets the flag be flipped instantly in either direction.

flowchart TD
  A["User opens the checkout page"] --> B["App asks SDK: is checkout_new_payment_sheet enabled?"]
  B --> C{"Answer"}
  C -- "True" --> D["Show the new payment sheet"]
  C -- "False" --> E["Show the old payment sheet"]
  C -- "No answer" --> F["Use the coded safe default"]
  F --> E
    

The safe default

A safe default is the answer your code uses when it cannot get one from Flagsmith, for example because of a network problem or because the flag was deleted. For almost every release flag, the safe default is “off”, meaning the old, proven behaviour. For an operational protection flag, the safe default might be “on”, because losing the protection would be worse. Decide the default flag by flag, and write it down.

Environment-level and person-level questions

An application can ask about a flag in two ways. The first asks for the Environment’s flags, with no information about the person. The answer is the same for everybody and is based on the Environment defaults. The second asks for flags for an identity, sending a user ID and perhaps traits. The answer is tailored through segments and overrides. Choose the first for simple switches, such as a site-wide maintenance banner. Choose the second whenever the flag must be different for different people, such as a rollout to ten percent.

When to ask

A common design question is whether to ask for a flag when the application starts or at the moment it is needed. Asking at start gives a consistent experience, because the user sees one version for the entire session, and it keeps the number of network calls low. Asking at the moment of use gives fresher answers, but can cause a screen to change halfway through someone’s task. For most products, fetch at the start of a session and refresh gently on a timer.

One flag, three stages, three independent switches. This separation is what makes a careful release possible.

The usual Environments are Development, where engineers experiment, Staging, where the product is tested as a whole, and Production, where real customers live. A boolean flag has a separate on or off state in each. Here is how one flag might move over a week.

Keeping Environments honest

Environments only help if they resemble each other. A common trap is a Staging Environment whose flag states drifted away from Production, so a test passes in Staging and a real customer finds a bug. Review the two side by side before big releases, and consider cloning Staging from Production to begin from a known state, where your version offers that option.

A flag that is the same for everyone is useful. A flag that is on for some people and off for others is powerful.

Identities and traits

An identity is Flagsmith’s name for one end user or account that your application tells it about, usually a user ID. A trait is a fact attached to an identity, such as “plan equals premium” or “country equals India”. The application sends these so Flagsmith can tailor the answer to the person.

Segments

A segment is a named rule that selects identities by their traits or by a percentage. Examples are “staff”, “premium customers” and “ten percent of all users”. A segment is defined once in the Project and reused by any flag.

Overrides

An override changes the answer of a flag for a segment or a person in one Environment. A segment override says “for staff, this flag is on, even though the default is off”. An identity override says the same for one specific person. Together, they let one boolean flag give different answers to different people.

Who wins when several rules apply

Flagsmith always takes the most specific rule. It checks for an identity override first, then segment overrides in their ranked order, then falls back to the Environment default.

flowchart TD
  START["Request: is flag X enabled for identity Y?"] --> Q1{"Identity override for Y?"}
  Q1 -- Yes --> R1["Use the identity override"]
  Q1 -- No --> Q2{"Does Y match a segment override?"}
  Q2 -- Yes --> R2["Use the highest ranked matching segment"]
  Q2 -- No --> R3["Use the Environment default state"]
    

Designing segments that last

Good segments describe who people are, not which feature they should get. A segment called “Beta programme members” can be reused by many flags for years. A segment called “New checkout testers” will be used once and then abandoned. Keep the list of segments short, give each a one line description, and remove those no flag uses any more.

Segment order matters when a person matches several. The segment ranked highest wins, so put the most specific or most important rules first. A typical order is: individual exceptions first, then staff, then named pilot groups, then percentage rollouts last. If you place a broad percentage rule above a narrow staff rule, staff members may be treated like everyone else and surprise you.

A boolean flag has only two answers, yet it can still be released gradually. The trick is that different people get different answers.

How a percentage rollout works

Create a segment that selects a percentage of all identities, for example ten percent, and give it a segment override that turns the flag on. Ten percent of people see the new behaviour. Ninety percent see the old. The next day, raise it to twenty-five percent, then fifty, then a hundred. At each step the team watches errors and complaints.

Why the same person stays in the same group

The split is steady for each identity. Flagsmith works out a position for the person from their identity, so the same person always lands in the same bucket. Someone in the first ten percent stays included as the percentage grows. Nobody flickers between the old and new experience when the app restarts. That steadiness makes slow rollouts calm for users and clean for analysis.

Choosing steps and signals

A rollout is only as safe as the signals you watch. Before starting, agree which measures matter, how long to wait at each step, and what number means “stop”.

The waits above are only examples. A tiny internal tool may move in an afternoon, and a payment system may wait a week at each step. What matters is that the plan is written before the first click, so the decision to widen is made against a standard rather than against excitement.

The most valuable boolean flag is often one you hope never to use.

What is a kill switch?

A kill switch is a flag that exists to turn something off quickly when it causes harm. It wraps a risky or expensive behaviour, such as a heavy recommendation engine, a third-party integration or a new payment route. Normally the flag is on and nobody thinks about it. In an emergency, an engineer switches it off, the risky behaviour stops, and the rest of the product carries on.

flowchart LR
  A["Normal day: flag is on"] --> B["Feature runs, users happy"]
  B --> C{"Incident detected?"}
  C -- No --> B
  C -- Yes --> D["Engineer flips flag off"]
  D --> E["Risky path stops within seconds"]
  E --> F["Product continues without the feature"]
  F --> G["Fix the cause, then flip it on again"]
    

Making a good kill switch

• Guard the whole risky path. The flag check should sit at the start of the behaviour, so turning it off truly stops the work.
• Make the off state boring. The product must work properly with the flag off. Test that path regularly, because it is the one you will use at the worst moment.
• Choose the default carefully. If Flagsmith cannot be reached, decide whether the safe behaviour is on or off, and code it.
• Keep it long lived. Unlike a release flag, a kill switch is meant to stay. Tag it “operational” so nobody deletes it as clutter.
• Practise. Flip it in Staging every quarter, so the team remembers where it is and what happens.

Rehearse the kill switch

A kill switch you have never used is a kill switch you cannot trust. Hold a short drill each quarter in Staging.

The most common use of a boolean flag is to hide work in progress. Done well, it lets teams merge code daily without fear.

The release flag

A release flag hides a feature that is not ready. Developers can merge unfinished code into the main code line every day, because the flag keeps it invisible. This avoids long lived side branches that drift away from the main code and cause painful merges. The flag is temporary. Once the feature is released and stable, the flag and the old code path are both removed.

The dark launch

A dark launch goes one step further. The new code runs in Production, but its results are not shown to users. A new recommendation engine might calculate suggestions silently while the old one still serves the page, so the team can compare the two and measure speed and load under real traffic before anybody sees the new output. Boolean flags control which parts run, and which results are displayed.

Why flags help teams merge daily

Many modern teams practise trunk-based development, which means everyone merges small changes into one shared main line of code every day, instead of working for weeks on private branches. The practice is popular because long lived branches drift away from the main code, and merging them later is slow and risky. The difficulty is that a half finished feature must not be visible to customers while it sits in the main line. A boolean release flag solves exactly that problem. The unfinished code is merged and deployed, but it stays behind a flag that is off. Companies such as Google and Facebook have spoken publicly about working with one main line of code for thousands of engineers, and hidden-by-default switches are a natural part of that style.

The bargain is simple: you gain small, frequent, low risk merges, and you pay by remembering to remove each flag once its feature is finished.

Boolean flags can also decide who gets a capability. This is powerful, and it comes with one important warning.

What is a permission flag?

A permission flag (also called an entitlement flag) switches a capability on for chosen customers or staff. A premium reporting tool might be enabled only for the “premium customers” segment. An internal admin screen might be enabled only for the “staff” segment. The flag is off for everyone by default, and segment overrides turn it on for the right groups.

How long should one live?

Unlike release flags, permission flags may be permanent, because they reflect a business rule: premium customers get this. Because they are permanent, they need clear owners, careful names and regular review, otherwise they become the hardest kind of flag to understand years later.

Designing entitlements well

When a permission flag follows a customer’s plan, let the plan itself drive the answer. The application sends a trait such as “plan equals premium”, a segment called “Premium customers” selects those identities, and the flag’s segment override turns the capability on. Now upgrading a customer is a data change in your own system, not a manual edit in Flagsmith. For one-off promises to a single customer, an identity override is acceptable, but record the reason in your own system, because a stray override with no explanation is easy to forget and hard to explain later.

Some flags exist to help engineers run the system, not to deliver features to customers.

What an operational flag does

An operational flag changes how the system behaves under stress. It might switch to a lighter version of a page during a traffic peak, reduce how often a background job runs, or send traffic to a backup service. It is close kin to the kill switch, but where the kill switch stops something entirely, the operational flag tunes the system.

A ladder of graceful degradation

Large systems rarely have only one emergency button. They have a ladder of smaller steps, each giving up a little to protect the whole. A retailer might prepare four boolean flags for a peak day. The first hides the personalised recommendations. The second reduces the number of search results. The third turns off the review summaries. The fourth shows a plain page without images. Each step is smaller and kinder than switching off the whole site, and the team climbs the ladder only as far as needed, then climbs back down as pressure eases.

Good names are the cheapest bug prevention available, and bad names are a famous source of mistakes.

The problem with “disable” flags

Suppose a flag is named “disable_new_checkout”. When the flag is enabled, the new checkout is disabled. To turn the checkout back on, someone must disable the flag. Read that twice and you will see how easily a tired engineer at midnight flips the wrong way. This is called a double negative, and it has caused real incidents.

Simple rules for names

• Name the behaviour when on. The name should describe what happens when the flag is enabled.
• Never start with “disable” or “no”. Flip the sense and rename. “Enable” or “show” words keep flipping honest.
• Start with the area. Prefixes such as checkout, search or profile make long lists easy to scan.
• Use one style. Lower case words with underscores is common. Choose and stick to it.
• Avoid people and dates. Names such as “johns_flag” or “march_launch” become meaningless fast.

The boolean answer you get depends not only on the rules, but also on what happens when something goes wrong. This chapter lists the cases.

The silent failure

The dangerous rows in that table are the quiet ones. A typo in a flag name does not crash anything. It just returns the default, and the feature simply never switches on, leaving the team puzzled for hours. Teams avoid this by keeping flag names in one shared place in the code, and by checking in Staging that flipping the flag really changes the screen.

Keep a register of defaults

Decisions about defaults are easy to forget, so write them down in one place. A small table in your team’s documents is enough, listing each flag, the default in code, the reason for that choice and the owner.

Where the flag check runs changes its speed, its cost and how fresh the answer is.

Client-side SDKs

A client-side SDK runs on the user’s own device, in a browser or a mobile app. It uses the public Environment key and asks Flagsmith for flags for the current user, then keeps a copy. The key is safe to be visible, because it can only read flag values for one Environment.

Server-side SDKs

A server-side SDK runs on your own backend. It uses a secret server-side key, which must never leave your servers. It may ask Flagsmith for each decision, or it may use local evaluation.

Local evaluation

Local evaluation means the server downloads the complete rule set for an Environment once, keeps it in memory and decides flags itself, without a network call per decision. It is extremely fast and greatly reduces requests. The trade-off is freshness: changes reach the server on a refresh schedule, so a flip may take a short while to show.

How fast does a flip take effect?

People are often surprised that a kill switch is not instant everywhere. A mobile app that cached flags at start may keep the old answer until it next refreshes or restarts. Some setups offer near real-time updates for client applications, while others rely on polling timers, so check what your SDK and plan support. Know your refresh interval, write it on the runbook, and design kill switches knowing that “seconds” may really mean “within a minute or two”.

Mobile apps and the stale answer

Mobile apps face a special challenge. A phone may be offline, or may keep an app open in the background for days. A flag value fetched on Monday may still be in use on Thursday. Plan for this in three ways. Refresh flags whenever the app returns to the foreground. Treat flags that affect safety, such as a kill switch, as needing a short refresh interval. And remember that older versions of your app remain in the world for months, so a flag must keep working for them until the last old version is gone.

Architects divide a system into the place where humans decide and the place where applications ask. Flagsmith follows that pattern.

The control plane is where people manage configuration: creating flags, editing segments, flipping states. The data plane is where high volume requests are served: millions of applications asking “is this flag on for this person?”. Your decision to flip a boolean happens in the control plane, and its effect is carried by the data plane.

flowchart LR
  subgraph CP["Control plane"]
    ADM["Dashboard used by your team"] --> API["Management API"]
    API --> DB[("Primary database")]
  end
  subgraph DPL["Data plane"]
    LB["Load balancer"] --> FE["Flag evaluation service"]
    FE --> CACHE[("Cache")]
  end
  DB --> FE
  APP["Your web or mobile app with SDK"] --> LB
  SRV["Your backend with SDK"] --> LB
    

What happens when you click the toggle

The split has a practical benefit: if the dashboard is slow or briefly unavailable, applications can still be served their flags. It also means the heavy daily work of editing and importing never slows the customers using your product.

Every flag should have a short, planned life. The ones with a planned ending are the ones that never become a problem.

flowchart LR
  A["Create flag in Project"] --> B["Enable in Development"]
  B --> C["Test in Staging"]
  C --> D["Release gradually in Production"]
  D --> E{"Stable and fully released?"}
  E -- Yes --> F["Remove flag checks from code"]
  F --> G["Delete or archive the flag"]
  E -- No --> H["Adjust or switch off"]
  H --> D
    

The stages in words

Create. Name it clearly, describe it, tag it and plan its removal. Develop. Enable it in Development while engineers build. Test. Enable it in Staging for testers. Release. Introduce it to real customers gradually in Production. Stabilise. Watch for a calm period after full release. Remove. Delete the flag check and the old code path, release that clean-up, and only then delete the flag in Flagsmith.

The last two steps are the ones most often forgotten. A flag left behind turns into hidden complexity, because the old code path is still there, untested, waiting to be woken by a mistake.

How long should each kind of flag live?

A flag doubles the number of paths your code can take. Testing must take that into account, or the flag becomes a hiding place for bugs.

Two paths, two sets of tests

Every boolean flag creates two behaviours: the old one when off, and the new one when on. Both must be tested. Teams that test only the new path discover, on the night they flip the kill switch, that the old path quietly broke weeks ago. The simplest rule is that every flag check has at least one test with the flag on and one with the flag off.

The combination problem

With one flag there are two combinations. With two flags there are four. With ten flags there are one thousand and twenty-four. Nobody tests them all, so the sensible approach is to keep flags independent. Each should control one behaviour and should not depend on the state of another. When two flags must be related, such as a new page that needs a new service, make that relationship explicit in the code and in the descriptions.

Testing in Staging

Staging is the place to rehearse real flips. Before launch, flip the flag on and off in Staging with the real application, confirm the screen changes both ways, and confirm the audit log recorded it. If you will use a percentage rollout, test it with a few named test users and confirm they land in the groups you expect.

A short test checklist for every flag

• With the flag on, the new behaviour works from start to finish.
• With the flag off, the old behaviour still works and nothing is broken.
• With no answer at all, the coded default behaves as intended.
• Flipping the flag while the application is running does not corrupt anything that is half done.
• The flag name in the code is exactly the name in Flagsmith.
• The audit log shows the flip with the right person and time.

Flags are borrowed convenience. If you never repay the loan, interest accumulates in the form of confusion and risk.

What is flag debt?

Flag debt is the pile of switches that have served their purpose but still live in code and in Flagsmith. Each one adds a little complexity: a branch nobody tests, a name nobody remembers, a risk that someone flips it by accident. A few are harmless. Hundreds are a hazard.

Spotting stale flags

A stale flag is one that has been fully on, or fully off, in every Environment for a long time. Look for release flags older than a few weeks, flags with no owner, and flags whose description is empty. Newer Flagsmith versions can help highlight such features, and tags and last changed dates help you find them on any version.

The safe order of removal

Ownership and expiry notes

The most reliable defence against flag debt is a short note in the description of every release flag: who owns it, what it protects and the date by which it should be gone. When that date passes, a reminder goes to the owner, and silence is treated as a signal that the flag is probably safe to remove after a quick check. Teams that adopt this habit rarely find themselves with hundreds of mysterious switches, because each one carried its own retirement plan from birth.

A boolean flip can change what every customer sees. Treat the right to flip it with the respect you give the right to deploy code.

Permissions at three levels

Flagsmith controls access at the Organisation, Project and Environment levels. For boolean flags, the most important permission is the one that lets a person change a flag’s state in a given Environment. Give it widely in Development, to a smaller group in Staging, and to a small named group in Production. People are best given permissions through groups, such as “Release Group”, rather than one by one.

Approvals and scheduling

On plans that offer them, change requests require a second person to approve a change before it takes effect, which is the software equivalent of a pilot and co-pilot reading the checklist together. Scheduling lets a team set a flag to change at an exact time, such as nine in the morning on launch day, so nobody has to be awake at dawn. Always rehearse a schedule in Staging and check the time zone shown on screen.

Two lanes of change

The standard lane covers routine changes, such as raising a rollout from ten to twenty-five percent, and needs the normal permission and a note in the team channel. The emergency lane covers urgent actions, such as switching off a failing feature, and is intentionally fast. The emergency lane must still leave a trail: a message in the incident channel and a short review the next working day.

Handover and on-call

The most stressful moment to learn who may flip a switch is during an incident. Make the on call engineer a member of the Release Group for the duration of their shift, or give them a documented route to ask someone who is. Keep an up to date page with the names of the most important kill switches, what each does, and what the safe default is. When a new engineer joins the rota, walk through that page together once. It takes ten minutes and prevents a very bad night.

A flag platform can change what every customer sees. It deserves the same care as any system that can alter production.

Know your keys

What an outsider can see

Anything sent to a browser or phone can, in principle, be read by the user. That means the names of flags sent to a client may reveal unannounced features to a curious visitor. Where your version offers the option, hide disabled flags from client applications, so only features that are on are visible. Avoid putting secrets, internal code names or private commentary in flag names or descriptions that clients can read.

Flags are not locks

Never rely on a flag alone to protect something sensitive. The flag decides what the screen shows. The server must still check that the person is allowed to see the data. Treat the flag as a convenience for honest users, and the server check as the guard for everyone else.

Practical protections

• Separate keys per Environment. A test build should never hold a Production key.
• Store secrets in a vault. Never in chat messages, documents or code files.
• Rotate on a schedule. Replace keys every few months and after any staff change that could have exposed them.
• Limit who flips Production. A small named group, with approvals where the plan allows.
• Turn on two-step sign-in. A stolen password alone should never be enough to flip a live switch.

Flipping a flag is easy. Knowing what the flip did is the real skill.

The audit log

The audit log is a diary of changes. For each flip it records who did it, when, and what the earlier value was. When a customer reports that something vanished at three in the afternoon, the audit log turns guesswork into a thirty second lookup, and tells you exactly how to undo the change. How long history is kept can depend on your plan.

Webhooks and integrations

A webhook is an automatic message sent from Flagsmith to another system when something happens. Many teams connect it to a chat channel so that each Production flip is announced to everyone. Flagsmith also provides integrations with tools such as Datadog and Slack, so that a flag change appears as a marker on the same graph as error rates and response times.

This pairing is extremely powerful, because most production incidents are caused by a change, and flag flips are changes. When a graph shows a spike, the first question, “what changed just before?”, is answered by the marker on the graph.

A simple flag health view

Many teams build a one screen view of flag health, using tags and last changed dates. It lists the number of flags by kind, the oldest release flag, flags with no owner, flags changed in the last week and flags on in Production for everyone for more than a month. A glance at that screen each week keeps debt visible, and visible debt gets paid down.

These traps appear in almost every company that adopts feature flags. Learn them now, and avoid paying for them later.

More small mistakes worth naming

• No safe default in code, so a flag outage becomes a product outage.
• Flipping a flag in Production before rehearsing it in Staging.
• Mixing the enabled state with a “true” or “false” value in the same feature.
• Letting Production permissions widen over time, because “just this once” was never undone.
• Putting a Production key in a test build.

Things will go wrong. Calm teams are the ones that already know what to do.

Scenario one: the wrong flag was flipped in Production

The first move is always to put it back to its previous value, which the audit log shows. Only after customers are safe should you ask how it happened. Teams that rehearse this typically recover in a minute or two.

Scenario two: the flag is on but nothing changed

Check three things in order. Is the application reading the right Environment key? Has it refreshed since the flip, or is it still holding a cached answer? Is the flag name in the code exactly the same as in Flagsmith? Most “it does not work” reports end at one of these three.

Scenario three: the flag works for some people but not others

Walk down the evaluation ladder from Chapter 9. Look for an identity override, then segment overrides and their order, then the Environment default. Confirm that the traits the segment needs are actually sent by the application, in the right format.

Scenario four: a flag was deleted while code still used it

The application falls back to its coded default, which is why defaults matter. Recreate the flag with the same name, restore its states from what the history shows, and plan the clean removal from code before deleting again.

Scenario five: a secret key leaked

Scenario six: Flagsmith is unreachable

Applications should be designed so that the worst case is boring. SDKs can keep serving the last known values, and your code supplies defaults for anything missing. For a flag that protects something essential, such as the ability to log in, decide the default carefully and test that path on purpose.

Scenario seven: a flip works on the website but not in the mobile app

This is usually a freshness problem rather than a broken flag. The web page fetches flags every time it loads, while the app may be holding values fetched earlier. Check when the app last refreshed, whether it is an older version that never asks for this flag, and whether the app is pointing at the correct Environment key. If the flag is a kill switch, this is the moment to remember the refresh interval from your runbook, and to decide whether it is short enough for the risk the switch protects.

A boolean check is tiny, but a busy product makes billions of them. Good design keeps each one cheap.

Ask once, decide many times

The core idea is to separate fetching flags from checking them. Fetching is a network call and takes milliseconds. Checking, once the flags are in memory, takes microseconds. A well built application fetches at the start of a session or on a timer and then makes hundreds of checks from memory.

flowchart LR
  U["Millions of users"] --> APPS["Your application servers"]
  APPS --> SDK["SDK with local cache"]
  SDK -- "periodic refresh" --> PROXY["Optional local proxy"]
  PROXY -- "occasional sync" --> FS["Flagsmith platform"]
    

A small capacity thought experiment

Suppose an application serves one hundred thousand requests per second at its busiest moment. If every request caused a fresh flag lookup, the platform would need to answer one hundred thousand questions per second, which is wasteful. With caching inside each application server, perhaps only one lookup per server every thirty seconds is needed. With two hundred servers that is about seven requests per second, a reduction of over ten thousand times, and users still get a decision in microseconds from memory.

Resilience comes free with the design

Delivery of flags is separate from the dashboard, so a dashboard outage does not stop evaluation. SDKs can keep serving the last known values if the network is down. And your own code defines defaults, so the worst case is a safe and familiar experience rather than an error page. Companies that serve very large traffic, such as Netflix and Google, speak often about designing for failure and for cost, and a flag lookup deserves the same thought as any other network call.

Counting the cost

Flag usage is typically measured in requests to the platform, not in the number of checks your code makes. That is why caching is both a speed measure and a cost measure. A mobile app with two million users that fetches flags three times a day makes six million requests a day. If a bug makes it fetch on every screen change, that number can grow many times over without anyone touching a flag. Review the usage page each month, and treat an unexplained jump as a bug in the application, not as growth.

Ideas become clear when applied. Follow one flag through a complete launch for a fictional retailer called Northwind.

The situation

Northwind sells goods through a website and a mobile app. A team of about twenty engineers is replacing the payment sheet in its checkout. The change is important and risky, because a broken checkout means lost sales. The team decides to use one boolean flag named “checkout_new_payment_sheet”, tagged as a release flag and owned by the Store team.

What went right

At no point did the team deploy to change what customers saw. Each step was a click, each click was recorded, each was reversible within seconds, and each decision was made with graphs in front of the team. If the one percent stage had shown a rise in errors, the flag would have been flipped off and customers barely affected.

What the team learned afterwards

A week after cleaning up, Northwind held a short review. Three lessons were written on one page. The first was that rehearsing the flip in Staging caught a misspelled flag name in the mobile app before any customer saw it. The second was that the one percent step was long enough to reveal a slow database query, which was fixed before reaching ten percent. The third was that the removal ticket created on day one made clean-up routine rather than a chore nobody owned. Reviews like this turn a single launch into lasting habits for every launch afterwards.

Few teams start from nothing. Most already have switches hidden in configuration files, environment settings and database tables.

Why homemade switches struggle

A homemade switch, such as a setting in a file, is perfectly reasonable for a handful of toggles. Trouble arrives with growth. Changing the file needs a deployment, so it is not instant. Nobody records who changed it. It cannot be targeted at a percentage or a group. There is no permission control, so anybody with file access can alter it. A managed platform supplies those missing pieces, and the structure of Projects, Environments and permissions is the part homemade systems tend to lack and later regret.

The four kinds of flag

Practitioners often sort flags into four groups, a classification popularised by engineers writing on well known software design sites. Release flags hide unfinished work and are short lived. Experiment flags split users to measure which version performs better. Operational flags protect the system and may live for years. Permission flags give certain customers or staff special access and may be permanent. Knowing the kind tells you how long a flag should live and who should be allowed to change it.

No design is perfect. Knowing both sides lets you decide with open eyes.

When a boolean flag is not the right tool

If a value is a true business rule needing legal review, such as a tax rate, it belongs in a controlled data store. If something needs complex relationships and queries, it belongs in a database. If a change is permanent and risk free, put it straight into the code. And if you need to compare several versions, reach for a multivariate feature instead of stacking boolean flags. A healthy Flagsmith holds switches and settings, not the whole configuration of the company.

A short list to keep nearby. If you do these ten things, you will avoid most of the pain described in this guide.

Keep this table nearby while reading documentation or talking with your team.

Quick answers to the questions that come up most often.