Three short definitions come first: the feature flag, the platform, and then the Project itself.

The feature flag

A feature flag (also called a feature toggle) is an on and off switch placed inside software. The code for a new feature is already deployed, but the flag decides whether users can see it. Flip it on and the feature appears. Flip it off and it disappears, with no new release needed. Teams use flags to release slowly, to test ideas, to hide unfinished work and to switch off a misbehaving feature in seconds.

The platform

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

The Project

A Project is the container for everything that belongs to one application, product or service. It sits directly below the Organisation and directly above Environments. Inside a Project you define your features, create your segments (rules that pick groups of users), label things with tags, and set rules about who on your team may do what. When you open Flagsmith to do real work, you almost always open a Project first.

One flag is easy. A whole product’s worth of flags, changed by many people across many stages, is a different problem entirely.

The problem Projects solve

A growing product collects flags the way a garage collects boxes. Some are brand new, some are half forgotten, and some are so old that nobody dares touch them. Without a clear home, four questions become impossible to answer. What flags does this product have? Who owns each one? What is each one doing in each stage? And what happens to the product if one of them is changed by mistake?

What large companies teach us

Engineering organisations known for rapid releases, such as Amazon, Netflix and Etsy, have all described in public talks and articles the idea of separating deployment from release: code goes out quietly, and a switch decides when users see it. Etsy in particular has written about “config flags” as a way to deploy many times a day with confidence. The same idea scales down. Whether you have five flags or five thousand, the switch is only trustworthy if it lives in a place with clear owners, clear stages and a clear history. That place is the Project.

The cost of having no home

Teams who skip structure often pay in three ways. First, time: engineers spend hours hunting through code to learn what a switch does. Second, risk: a flag with no owner and no history is one that nobody dares touch, and one that someone eventually touches wrongly. Third, trust: when two people disagree about what is on in Production, they lose faith in the whole approach and go back to slow, careful releases. A Project removes all three costs by giving every switch a place, an owner and a history.

Flagsmith is a tree with three main levels. Knowing exactly where the Project sits explains most of its behaviour.

At the top is the Organisation, which holds people, groups, billing and company-wide rules. Below it are Projects. Below each Project are Environments. Inside each Environment are the live values of every feature and the end users, called identities, whose flags are being worked out. The diagram shows a fictional company, Acme Corp, with two Projects.

graph TD
  ORG["Organisation: Acme Corp"] --> P1["Project: Checkout Service"]
  ORG --> P2["Project: Mobile App"]
  P1 --> F["Features defined once"]
  P1 --> SEG["Segments"]
  P1 --> TAG["Tags"]
  P1 --> PERM["Project permissions"]
  P1 --> E1["Environment: Development"]
  P1 --> E2["Environment: Staging"]
  P1 --> E3["Environment: Production"]
  E3 --> FS["Feature states and values"]
  E3 --> ID["Identities and traits"]
  E3 --> KEY["Environment API keys"]
    

The key split to remember

A feature is defined once, at the Project level. Its value is stored separately in each Environment. So a feature called “new transfer screen” exists once in the Mobile App Project, but it may be on in Development, on for a small group in Staging, and off in Production. That split is what makes careful, step by step releases possible.

Open a Project and you will find a handful of areas. Each has a simple job.

Notice what is not on this list: people management and billing. Those belong to the Organisation. A Project is about the product’s behaviour, not about the company’s accounts. This separation lets a product team work freely inside its Project while a platform or security team keeps its grip on the account above.

An Environment is one stage of a product’s journey. Every Project has at least one, and most have three or more.

What is an Environment?

An Environment is a separate copy of the live values of your features. The usual three are Development, where engineers experiment freely, Staging, where the product is tested as a whole before release, and Production, where real customers use the product. Flagsmith normally creates starter Environments for a new Project, and you can add more, such as one for a quality assurance team or one per region.

What each Environment owns

Every Environment has its own API keys, so a test build can never accidentally read Production values. It has its own feature values, so a feature can be on in Development and off in Production. It has its own identities, which are the end users the product has told Flagsmith about, and its own overrides, which are special rules for a particular segment or person.

Keeping Environments alike

Environments only help if they behave similarly. A common trap is a Staging Environment whose flag values drifted far from Production, so tests pass in Staging and fail in real life. Flagsmith lets you create a new Environment by cloning an existing one, which is a quick way to start from a known good set of values. Teams often review Staging and Production side by side before big releases to make sure they differ only where intended.

How a change travels from stage to stage

Teams that use Environments well follow a steady promotion path. A change is first made in Development, where it is cheap to be wrong. Once it behaves as intended, the same change is applied in Staging, where testers confirm it works together with everything else. Only then is it applied in Production, often with a small audience first. Because the feature definition is shared, the only thing that moves is the state, which makes each step small and easy to reverse.

When three Environments are not enough

Some products add a few more. A quality assurance Environment gives a dedicated test team a stable place that developers do not disturb. A demo Environment lets a sales team show features to prospects without touching real data. Large companies sometimes add a regional Environment for a country that needs different behaviour. The rule is to add an Environment only when a group of people truly needs a separate set of values, because every extra Environment is one more place that can drift out of step.

The word “feature” in Flagsmith is broader than a simple on and off switch. It covers three useful kinds of control.

Kind one: the standard flag

A standard flag is the plain switch. It is either enabled or disabled in each Environment. It can also carry an optional value, such as a short piece of text or a number, which lets one feature both switch something on and say how it should behave.

Kind two: remote configuration

Remote configuration means changing settings of a running application without releasing new code. Instead of fixing the number of items shown in a list inside the code, the application asks Flagsmith for the value. If the team decides the list should show twelve items rather than ten, they change the value in the dashboard and the app follows within moments. In Flagsmith, a feature’s value serves this purpose.

Kind three: multivariate features

A multivariate feature offers several possible values and splits users between them by percentage. For example, a button might say “Buy now” for forty percent of users, “Get it today” for thirty percent and “Add to basket” for another thirty. This is the foundation of experiments, where a team measures which version works best. The names of these options are defined in the Project, and the percentage split is chosen per Environment.

What a feature carries

Each feature has a name, which is how your code finds it, and a description, which explains in plain words what it controls. It may also have tags, a creation date and an owner. The name is permanent in practice: because code refers to it, renaming a feature carelessly can break an application. Treat names with the same respect you give names in a public interface.

Choosing the right kind of feature

If you are unsure which kind to pick, ask a short series of questions. Is it only a question of showing or hiding something? Use a standard flag. Does the app need a number, a message or a limit that you want to adjust live? Use a value, which is remote configuration. Do you want to compare several versions with different groups of users? Use a multivariate feature. Many real features combine them: a flag that enables a new search page, together with a value saying how many results to show.

A feature’s value can be plain text, a number or a true or false answer. Keep the value simple. If a value starts to look like a whole document, the team is probably using the flag system as a database, which is a different job and best given to a proper data store. Good values are short enough to read at a glance in the dashboard.

This chapter explains the single most important distinction inside a Project, and the one that confuses almost every newcomer.

Two different things with similar names

A feature definition is the existence of the feature: its name, its description, its type and its tags. It lives at the Project level and is shared by all Environments. A feature state is the live condition of that feature in one Environment: whether it is enabled, and what its value is. It lives in the Environment, so each Environment has its own state for every feature.

Why the design is clever

Because the definition is shared, every Environment agrees on what features exist, so your code can ask for a feature by name and always get an answer in any stage. Because the state is separate, each stage can differ safely. A feature that is still unfinished can be on in Development and off everywhere else, and moving it forward is as simple as changing its state in the next Environment.

What happens when a new feature is created

When you create a feature in the Project, Flagsmith makes it available in every Environment, by default switched off, so that nothing changes for real users until someone deliberately turns it on. This safe default matters. Some Projects also have a setting that controls whether new features start in the on or off position, so it is worth checking which default your Project uses before creating anything important.

A flag that is the same for everybody is useful. A flag that is different for different groups of people is powerful. Segments make that possible.

Identities

An identity is Flagsmith’s name for one end user or account that your application tells it about. It is usually a user ID. When the application asks for flags for an identity, Flagsmith can give an answer tailored to that person rather than a generic one.

Traits

A trait is a fact attached to an identity, such as “plan equals premium”, “country equals India” or “app version equals 4.2”. Applications send traits to Flagsmith, and Flagsmith remembers them for that identity.

Segments

A segment is a named rule that selects identities based on their traits, or on a percentage split. Examples: “premium customers”, “users in Germany on app version 5 or higher”, or “ten percent of all users”. Segments are defined once in the Project and can then be used by any feature in any Environment of that Project, which keeps rules consistent and easy to reuse.

flowchart LR
  APP["Your app sends identity and traits"] --> ID["Identity: user 4821"]
  ID --> T1["Trait: plan = premium"]
  ID --> T2["Trait: country = Germany"]
  T1 --> SEG1["Segment: Premium customers"]
  T2 --> SEG2["Segment: German users"]
  SEG1 --> RES["Feature value chosen for this user"]
  SEG2 --> RES
    

Where segments are used

A feature in a particular Environment can have segment overrides, which say, “for this segment, use a different value from the default”. A feature can also have identity overrides, which say the same for one specific person. This is how a team can give a new feature to employees first, then to a pilot group, and finally to everyone.

Writing good segment rules

A segment is made of one or more rules, and each rule compares a trait with a value. Common comparisons include “is equal to”, “is not equal to”, “contains”, “is in a list”, and, for numbers, “is greater than” or “is less than”. A special kind of rule splits users by percentage, which is how a team gives a feature to exactly ten percent of everyone. Rules can be combined, so that a person must match all of them, or any of them, depending on how the segment is built.

A percentage split is steady for each person: the same user lands in the same bucket every time, so a person in the first ten percent does not drop in and out as the app restarts. When the team widens from ten to twenty-five percent, the original ten percent stay included. This steadiness is what makes slow rollouts feel calm to users and clean to measure.

When several rules could apply to the same person, there must be a clear order for who wins. Understanding this order removes most confusion about “why is my flag showing the wrong value?”

For any one feature, in one Environment, for one identity, Flagsmith works through the possible sources of a value in order, from the most specific to the most general, and stops at the first that applies.

flowchart TD
  START["Request: feature X for identity Y in Environment E"] --> Q1{"Is there an identity override for Y?"}
  Q1 -- Yes --> R1["Use the identity override value"]
  Q1 -- No --> Q2{"Does Y match a segment override?"}
  Q2 -- Yes --> R2["Use the value of the highest priority matching segment"]
  Q2 -- No --> R3["Use the Environment default value"]
    

When the answer surprises you

If a person sees an unexpected value, walk down the ladder. First ask whether they have an identity override. Next ask which segments they belong to, and in what order those segments are ranked. Last, check the Environment default. Most puzzles end at step two, where two segments both match and the higher one wins. Also confirm that the application really is sending the trait the segment needs. A segment that depends on “country” will never match if the app never sends that trait.

A worked example with three shoppers

Take the feature “checkout_new_payment_sheet” in Production. The Environment default is off. There is a segment override for “Staff” that turns it on, ranked first, and a segment override for “Ten percent of all users” that also turns it on, ranked second. There is one identity override that turns it off for a customer whose bank has reported a problem.

Working a few examples like this on paper is one of the best ways to build confidence. When a real report arrives that “the page is wrong for one user”, you can fill in a row like these for that person and find the answer in a minute.

The boring habits are the ones that keep a Project healthy for years. Names and labels are the best examples.

Tags

A tag is a small coloured label that you attach to a feature. Tags have no effect on how a feature behaves. They exist purely to help humans sort, search and filter. Useful tags answer questions such as: what kind of flag is this (release, experiment, operational, permission)? Which team owns it? Is it temporary? Is it related to a particular project milestone?

Naming conventions

A good name tells a stranger what the feature does without opening the description. Teams commonly choose a consistent style, such as lower case words separated by underscores, and often begin names with the area of the product, for example “checkout_new_payment_sheet”. Flagsmith can enforce a pattern for feature names at the Project level, so mistakes are caught when the feature is created rather than months later. Check the Project settings to see how your version handles this.

Owners and descriptions

Every feature benefits from a short description and a named owner, which is a person or team responsible for it. When a flag has been on for six months and nobody knows why, the owner is the one who answers. Without owners, old flags pile up like unclaimed luggage.

A tag family that works

Teams that keep tidy Projects usually keep their tags to a small family, often two kinds. The first kind describes what the flag is: release, experiment, operational or permission. The second kind describes who owns it: a team name such as payments, search or mobile. Adding a third kind, such as “remove by end of quarter”, can also help. More than three families tends to confuse people, and tags that nobody maintains are worse than none at all.

A Project has a settings page. A few choices there quietly change how the whole team works, so they deserve a calm look on day one.

Name and identity

The Project has a name, which should match the product it serves, so that everyone recognises it. Pick a name that will still make sense in three years. “Mobile App” is better than “Q3 Mobile Experiments”, which will confuse people the moment the quarter ends.

Feature name rules

As mentioned earlier, many setups allow a rule for how feature names may be written, such as a required pattern or lower case only. Switching this on early prevents a messy mixture of styles and makes searching easier. Switching it on late can be awkward, because existing names may not match, so decide before the list grows.

What is sent to applications

Some Projects offer a choice to hide disabled flags from applications. If enabled, the application only receives flags that are currently on, which makes the data smaller and keeps unreleased feature names out of public view. This can matter for a website, where a curious visitor could otherwise look at the data and discover the name of an unannounced feature. The trade-off is that your code must handle the absence of a flag sensibly, which a safe default already does.

Defaults for new features

Another useful choice is what state a new feature starts in. The safest approach is for new features to start switched off in every Environment, so that creating a feature never changes what customers see. Check your Project’s behaviour so nobody is surprised.

Decisions to make on day one

Before the first real feature is created, a short meeting of fifteen minutes can settle four questions. What style of name will every feature follow? Which tags exist, and who may add new ones? What should happen when a new feature is created, switched off everywhere or not? And who is the named owner of the Project, so that questions have a single address? Writing the answers on one page and pinning it where the team looks daily costs almost nothing, and saves many small arguments in the months ahead.

The Organisation decides who belongs to the company. The Project decides which of those people may touch this particular product.

Two layers of control

Permissions inside a Project come in two layers. Project-level permissions control the shape of the Project: who may view it, who may create or delete features, who may manage segments, who may create tags, who may read the audit log and who may add Environments. Environment-level permissions control the values: who may change a feature’s state, who may manage identities and, where available, who may create or approve change requests. These can be given to individual people or, better, to groups.

The principle of least privilege

Least privilege means giving each person only the power needed for their job. In a Project this usually means wide access in Development, narrower access in Staging and a very small group in Production. Many people can create features, but only a few can switch them on for real customers.

Groups make it manageable

Instead of listing individual names, give permissions to named groups, such as “Payments Team” or “Release Group”. When someone joins or leaves a team, you change the group, not dozens of separate permissions. Groups are created at the Organisation level and then attached to Projects.

A sample permission grid for one Project

The grid below shows how a store team might arrange access. It is an example of a design, not a copy of real permission names, which differ between versions.

The pattern to copy is the narrowing towards Production, with one small group trusted to change what customers see. When that group is on call, they also carry the responsibility to leave a short note after any emergency change.

A Project that nobody can observe is a Project nobody can trust. These tools make changes visible.

The audit log

The audit log is a diary kept by the Project. Every important change, such as a feature being created, switched on or edited, is recorded with the person, the time and what changed. When a customer reports that something vanished at three in the afternoon, the audit log turns guesswork into a quick lookup. How long history is kept can depend on your plan.

Webhooks

A webhook is an automatic message sent from Flagsmith to another system when something happens. A team may connect it to a tool that posts a note in a chat channel each time a Production flag changes, so everyone sees the change at once.

Integrations

Flagsmith also provides ready-made integrations with analytics, monitoring and communication tools, for example Datadog and Slack. When a flag change is lined up on a graph beside error rates, engineers can see within seconds whether a change helped or hurt. This pairing is powerful because most production incidents are caused by a change, and flags are changes.

Choosing what to send where

It is tempting to connect every notification to every channel, but a flood of messages teaches people to ignore them all. A sensible approach is to send only Production changes to the main team channel, send Development changes nowhere, and send unusual events, such as a deleted feature, to a smaller channel watched by the owners. Fewer, clearer messages are read. Many messages are muted.

The dashboard is where people decide. A different path carries those decisions to millions of users. Seeing both paths makes the Project’s role clear.

Control plane and data plane

Architects divide systems into a control plane, where humans manage configuration, and a data plane, where high volume requests are served. The Project’s pages, such as creating features and editing segments, are part of the control plane. When an application asks “what is this flag?”, it uses the data plane, through an Environment key.

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
    

Following one lookup

Notice that the Project never appears directly in that story. Its work was done earlier, when the team defined the feature and set the rules. At lookup time, only the Environment and its key matter. This division keeps the part that must be fast away from the part that must be careful.

Local evaluation

Some server SDKs can download the entire set of rules for an Environment once, and then decide flags inside your own server without asking again. This is called local evaluation. It greatly reduces delay and the number of requests, because decisions come from memory in microseconds. The cost is that updates reach the server on a refresh schedule rather than instantly.

Client-side and server-side SDKs

Not every SDK lives in the same place. A client-side SDK runs on the user’s own device, in a web browser or a mobile app. It uses the public client-side key and asks for flags for the current user. A server-side SDK runs on your own backend servers. It uses the secret server-side key and may ask for flags for many users, or download the entire rule set and decide locally.

The choice has a real effect on cost and speed. A mobile app asks once at start and caches, which is fine. A backend that makes ten thousand decisions per second should use local evaluation, so those decisions never leave the building.

A Project is born, grows, is reorganised and, eventually, retires. Planning for each stage saves pain later.

Deleting a Project removes everything inside it. Because that is such a large step, many companies make it an administrator-only action and require a short written note first. Before deleting, make sure no application still holds a key to one of its Environments.

A checklist before retiring a Project

• Confirm the product itself is switched off, and that no customer can still reach it.
• Search all code repositories for the Project’s Environment keys and remove them.
• Export or screenshot anything you need to keep, such as the list of features and segments for the historical record.
• Tell the groups attached to the Project, so nobody is surprised.
• Revoke the Environment keys, wait a short while to see whether anything complains, and only then delete the Project.

The Project exists to host flags, and every flag should have a short, planned life.

flowchart LR
  A["Create feature 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 from code"]
  F --> G["Delete or archive the feature"]
  E -- No --> H["Adjust or switch off"]
  H --> D
    

The stages in words

Create. The feature is defined once in the Project, with a clear name, description and tags. Develop. It is switched on in Development while engineers build. Test. It is switched on in Staging for testers. Release. It is introduced to real customers in Production, usually through segments and percentages. Stabilise. The team watches the product for a while. Remove. Once the feature is fully released and stable, the flag is taken out of the code, and the feature is deleted or archived in the Project.

The last two steps are the ones most often forgotten. A flag that stays forever turns into hidden complexity: every extra flag doubles the possible combinations of behaviour that the code can take, and old code paths grow dangerous because nobody tests them.

Plan the ending on the first day

The easiest way to avoid stale flags is to decide how a flag will end at the moment you create it. Add a short note to the description, such as “remove after full release, owner: payments team”. Some teams also create a ticket for the removal at the same time as the flag, and link the two. When the feature reaches everyone and the calm period passes, the ticket is already waiting. Without this habit, removal competes with every new feature for attention, and removal tends to lose.

The biggest design choice is what a Project should represent. Here are the common shapes, with their reasons.

graph TD
  ORG["Organisation"] --> PA["Project: Web and Mobile Store"]
  ORG --> PB["Project: Payments"]
  ORG --> PC["Project: Platform Shared Switches"]
  PA --> A1["Development"]
  PA --> A2["Staging"]
  PA --> A3["Production"]
  PB --> B1["Development"]
  PB --> B2["Staging"]
  PB --> B3["Production"]
  PC --> C1["Development"]
  PC --> C2["Staging"]
  PC --> C3["Production"]
    

How to choose

Ask three questions. First, do two parts of the system need to share the same switch? If yes, they probably belong in the same Project, because a feature belongs to only one Project and cannot be shared across them. Second, do the teams have different owners and different access rules? If yes, separate Projects give a natural wall. Third, how many features will the Project hold? A Project with several thousand features becomes hard to navigate, and that is often a hint to split by product area.

Three layouts for three kinds of company

A small startup with one product. One Project holds everything. Three Environments are enough. The team avoids splitting early, because splitting adds ceremony without adding clarity.

A mid-sized company with a handful of products. One Project per product, each owned by its team, plus a small shared Project for global switches such as a maintenance banner. Groups attach to Projects. This is the most common shape.

A large company with many microservices. A Project per team or per cluster of closely related services, so that ownership matches the organisation chart. Cross-service switches live in a shared Project that a platform team owns. A naming rule begins every Project with its team name so the long list stays readable.

A frequent question: one Project per customer?

If you run a business-to-business product with hundreds of customers, do not create a Project for each. A Project represents a product, not a customer. Different behaviour per customer is the job of identities, traits and segments, which let one feature behave differently for many customers inside a single Project. Creating a Project per customer multiplies setup, drifts definitions apart and makes cleanup nearly impossible.

Ideas become clear when applied. Let us build a Project for a fictional company called Northwind Retail.

The situation

Northwind sells goods through a website and a mobile app. A team of about twenty engineers, designers and product managers works on both. They want to launch a new checkout page, tune their search page during sales and offer early access to loyal customers.

Step by step

A day in the life

On Monday, a developer creates a new feature in the Project and enables it in Development. On Wednesday, a tester sees it in Staging. On Friday, the Release Group enables it in Production for staff only. The next week it moves to ten percent of users, and the team watches error rates on a graph connected to the Project. When all is calm, it goes to everyone. A month later, the developer removes the flag from the code and deletes the feature. The audit log holds the whole story.

Every design has strengths and costs. Knowing both lets you decide with open eyes.

The central trade-off: big Projects or small Projects

A big Project gives a single view of the whole product and makes it easy to share features between parts. It also gives everyone in it the same list, which can become crowded and risky when many teams touch it. Small Projects give clean walls and clear owners, but a switch that spans two services needs to be duplicated or coordinated. Most mature companies land in the middle: one Project per product or per team, with a small shared Project for truly global switches.

Build or buy

Many teams begin with a homemade solution such as a configuration file or a database table. For a handful of switches that is perfectly reasonable. As the product grows, someone must add a dashboard, permissions, history, fast delivery and security. Each is a small project, and together they become a product that does not earn money for the company. The Project model, with its definitions, Environments, segments, permissions and history, is the set of features that homemade systems tend to lack and later regret. If you expect more than a few dozen flags, or more than a few people changing them, a managed structure usually repays its cost.

When a flag is not the right tool

Flags are wonderful for behaviour that changes often, but they are not for everything. If a value is a true business rule that needs a proper audit and 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. And if a change is truly permanent and risk free, it is simpler to put it straight into the code. A healthy Project holds switches and settings, not the whole configuration of the company.

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

• Forgetting a safe default in code, so a flag outage becomes a product outage.
• Letting Production permissions widen over time, because “just this once” was never undone.
• Sending traits in inconsistent formats, so segments silently stop matching.
• Changing a feature’s value in Production before testing it in Staging.
• Using a Production key in a test build, which is exactly what separate Environment keys are there to prevent.

Spotting the warning signs early

Anti-patterns rarely arrive suddenly. They grow quietly, and a few simple signs tell you when to act. If new team members ask “what does this flag do?” more than once a week, your names and descriptions are failing. If the list of features is longer than anyone can scroll comfortably, it is time to split or clean. If Staging and Production disagree on many values, drift has begun. And if nobody can name the owner of a Production flag within a minute, ownership has been lost.

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 to put it back to its previous value. The audit log shows what that was. Only after customers are safe should you ask how it happened. Teams that rehearse this typically recover in a minute or two.

Scenario two: a feature was deleted but code still uses it

The application falls back to its coded default for that flag. If the default was chosen sensibly, users see the old behaviour and little is lost. If the default was careless, the feature misbehaves. Recreate the feature with the same name, restore its states from what the history shows, and then plan the proper removal from code before deleting again.

Scenario three: a segment matches the wrong people

A typing slip in a rule, such as “equals” where “contains” was meant, can include or exclude thousands of users. Check the rule, check the trait values the app actually sends, and use the segment override order to confirm which rule was applied. Testing a segment in Staging with real examples before Production avoids most of these.

Scenario four: Staging and Production drifted apart

Tests pass but real customers see problems. Compare the two Environments side by side, align them where they should match, and add a regular comparison to your release checklist.

Scenario five: an Environment key is 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 scheduled change goes out at the wrong time

On plans that support scheduling, a team can set a flag to change at a chosen moment, such as nine in the morning on launch day. The risk is a time zone mix-up. Always confirm the time zone shown on screen, rehearse the schedule in Staging, and name a person to watch the launch moment instead of trusting the schedule blindly.

Scenario eight: the plan limits are reached

If applications ask for flags far more often than expected, the account can approach the request allowance of its plan. What happens next depends on the plan, so learn it in advance. Set up a usage alert at a comfortable margin below the limit, and look for the application behaviour that causes the surge, such as asking for flags on every scroll.

A flag platform can change what every customer sees. Treat it with the same care as a deployment system.

The three kinds of key

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.
• Hide unreleased names. Where the option exists, hide disabled flags from client applications so unannounced features are not visible in public data.
• Limit Production changes. Give that power to a small, named group, and consider approval flows on plans that offer them.

A short security conversation for every new team

When a new team joins a Project, hold a ten minute conversation that covers four things. Which keys will you use, and where will they be stored? Who on the team may change Production, and how will others ask for a change? What is the safe default for each flag, and has it been tested? And how will you notice if something goes wrong, and who will you tell? These four questions turn abstract security rules into habits that a team can recall at three in the morning.

A Project, like a garden, needs regular weeding. The good news is that the weeding is simple and the tools help.

What is a stale flag?

A stale flag is a flag that has served its purpose but is still in the Project and in the code. Typically it has been fully on, or fully off, in every Environment for months. It no longer protects anything, and yet it adds complexity. Newer versions of Flagsmith offer help in spotting such features, and you can also find them by looking at tags and last-changed dates.

A monthly hygiene routine

• List old release flags. Filter by the “release” tag and sort by how long they have been unchanged.
• Ask the owners. A short message in the team channel is usually enough to confirm which can go.
• Remove from code first. Delete the flag check, release the code, and only then delete the feature from the Project.
• Review segments. Remove those no feature uses and tidy names.
• Review permissions. Compare who can change Production with your policy page.
• Read a sample of the audit log. Confirm that changes match expectations.

What to measure

Who is responsible for what?

A simple table called a RACI says who is Responsible (does the work), Accountable (owns the result), Consulted (gives input before) and Informed (told afterwards). Here is a sample for activities inside one Project.

The table is short on purpose. A one page agreement that people actually read beats a fifty page policy that is signed once and forgotten. Where a rule can be enforced by a setting, enforce it with the setting rather than a reminder email.

Two lanes of change

Not every change deserves the same care. The standard lane covers routine changes, such as moving a rollout from ten to twenty-five percent, and needs only the normal permission. 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 note in the incident channel, and a short review the next working day.

What changes when a Project grows from a dozen flags to thousands, and from a few users to millions?

Scaling the list

The Project scales through structure. At twelve flags anyone can remember them all. At twelve hundred nothing works without tags, naming rules, owners and regular cleanup. A common step is to split by product area once a Project becomes too large for one team to understand, while moving truly shared switches into a small platform Project.

Scaling the traffic

Volume is handled in the data plane. Applications serving millions of users should not ask Flagsmith a fresh question for each page view. Instead they use the caching and local evaluation behaviours of the SDKs, so only a small trickle of requests ever leaves their own network. Some deployments also place a lightweight proxy close to their applications, which answers most questions from a local copy.

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"]
  FS --> PRJ["Project and Environment rules"]
    

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 the user still gets a decision in microseconds from memory.

This is why architects who build for scale talk about moving decisions closer to where they are used. The same idea appears in content delivery networks, in database read replicas and in the local caches of large retailers and streaming companies.

Resilience

High availability means the system stays usable even when parts fail. Flagsmith’s design helps in three ways. 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 can define defaults, so the worst case is a safe and familiar experience rather than an error page.

Three habits that keep large Projects fast

Ask once, decide many times. Fetch flags at the start of a session or on a timer, and let the app make hundreds of decisions from memory. Fetch only what you need. Where the option exists, hide disabled flags or fetch a single flag, rather than downloading everything for every call. Keep defaults close to the code. A well chosen default means a slow or missing answer from Flagsmith is only a small inconvenience, never an outage.

Companies that handle very large traffic, such as Netflix and Google, speak often about designing for failure and for cost. A flag lookup is a network call like any other, and good architects treat each call as something worth designing, not something to discover on an invoice.

Few teams start from nothing. Most already have switches hidden in configuration files, environment settings and database tables. Adoption is about bringing order to what exists.

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, and live for weeks. Operational flags let engineers reduce load or disable heavy features in incidents, 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.

Training the people

A tool alone changes little. People need to learn three habits: always release behind a flag, always define a safe default, and always remove the flag when the work is done. A short workshop and a one page cheat sheet beat a long manual. It also helps to appoint a flag champion in each team, someone who answers questions and keeps naming consistent.

How to tell it is working

After a few months, look at four simple measures. Release frequency: are teams shipping more often? Reversal time: how long does it take to undo a bad change? Flag age: are release flags being removed on schedule? Surprise count: how many times did someone say “I did not know that flag was on”? Falling surprise counts are the clearest sign that the Project has become the single source of truth.

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 the documentation or talking with your team.

Quick answers to the questions that come up most often when people first meet the Project.