Before learning how Flagsmith models a feature, let us feel the problem it solves: the problem of changing a live product without fear.

What do we mean by a software feature?

In everyday speech, a feature is any capability of a product that users can notice. A search box is a feature. A “pay with a saved card” button is a feature. A new recommendation engine is a feature. Even a number, such as the maximum size of a file a user may upload, can be treated as a small feature, because changing it changes what users can do.

The old way: features hidden inside releases

In the traditional way of building software, a feature was tied to a release. The developers wrote the code, tested it, packed it into a new version of the product, and put that version live. The moment the new version reached the servers, every user saw the new feature. If the feature had a hidden bug, every user met it at the same time. If the business wished to change the feature, for example to reduce a limit from fifty files to twenty, a developer had to change the code, test again, and release again.

This meant that three different decisions were glued into one event: when the code is written, when the code is put on servers, and when users see the behaviour. Gluing them together made every release feel like a high-stakes performance.

What teams really want

A short story

Kavya works at an online learning platform. Her team has built a new “live class reminder” that sends a notification fifteen minutes before a class begins. Instead of releasing it to all two million learners at once, the team wraps it in a Flagsmith feature. On Monday it is switched on for the team’s own accounts. On Tuesday it is on for one percent of learners. A dashboard shows that reminders arrive late for people in one region, so the team pauses, fixes a scheduling bug, and continues. By Friday every learner has the reminder, and nobody ever saw a broken version. The code had been on the servers since Monday morning. Only the feature’s state changed.

In Flagsmith, a feature is a named item, defined once inside a project, that can carry an on and off position, a stored value, or both, with a separate answer in every environment.

A quick map of the Flagsmith world

Flagsmith is an open-source platform for feature flags and remote configuration. A feature flag is a switch that turns behaviour on or off without a new release. Remote configuration means storing values, such as numbers and text, that an application reads while running, so that they can be changed without a release. Flagsmith arranges everything in a simple tree.

flowchart TB
    PRJ["Project: Learning Platform"] --> FEAT["Feature: live class reminder"]
    FEAT --> DEF["Shared definition: name, description, tags, type"]
    FEAT --> ED["Development state"]
    FEAT --> ES["Staging state"]
    FEAT --> EP["Production state"]
    ED --> ED1["Enabled: yes, Value: 15 minutes"]
    ES --> ES1["Enabled: yes, Value: 15 minutes"]
    EP --> EP1["Enabled: no, Value: 15 minutes"]
    

The simplest definition

If the project is the hotel’s key board, a feature is one labelled hook. Its label (the name, the description, the tags) is shared by everyone. Whether a key hangs on the hook (the feature is enabled), and which key (the stored value), is decided separately in each environment.

The three questions a feature answers

Whenever an application asks Flagsmith about a feature, it is really asking up to three questions.

• Is it enabled? The on and off position. This is the basic flag.
• What is its value? An optional piece of stored information, such as a number, a piece of text, or a small block of structured data. This is remote configuration.
• Which variation applies to this user? For features with several variants, Flagsmith picks one for each user according to the percentages you set. This is a multivariate feature.

Other words you will hear

Different teams call the same idea by different names: feature toggle, feature switch, feature flag, or config flag. In Flagsmith’s own screens and documents, the word feature is used for the item, and the phrases feature flag and remote config describe what you can do with it. A person may say, “Enable the feature in staging,” meaning that the feature’s state in the staging environment should be set to enabled.

A feature is a small package of information. Let us open the package and look at each part, separating what is shared from what is private to each environment.

flowchart LR
    F["A Flagsmith feature"]
    F --> S["Shared across the project"]
    F --> P["Private in each environment"]
    S --> S1["Name or key"]
    S --> S2["Description"]
    S --> S3["Tags"]
    S --> S4["Type: flag, config, or multivariate"]
    S --> S5["Owners and archived status"]
    P --> P1["Enabled or disabled"]
    P --> P2["Value"]
    P --> P3["Variation percentages"]
    P --> P4["Segment overrides"]
    P --> P5["Identity overrides"]
    P --> P6["Scheduled or pending changes"]
    

The shared parts

The private parts, per environment

Value types

A feature’s stored value can carry different kinds of information. Typically you can store text, whole numbers, true or false values, and, in many versions, structured data in a common text format used to describe objects. Choose the simplest type that fits. A single number is easier to understand, validate, and test than a large block of structured data. If you do store structured data, keep it small and describe its shape in the feature’s description, because mistakes inside a free-form value are not caught until your application tries to use it.

Features come in a few flavours. Choosing the right flavour keeps your design simple and your code easy to read.

Flavour one: the plain feature flag

A plain feature flag carries one piece of information: enabled or disabled. It answers a yes or no question, such as “Should this user see the new checkout?” It is the simplest and the most common flavour, and it is the right choice whenever the real question is whether something happens at all.

Flavour two: remote configuration

Remote configuration stores a value that your application reads, such as the number of items in a carousel, the text of a banner, or the time allowed for a request. It answers “how much?” or “what text?” instead of “yes or no?” A single Flagsmith feature can carry both: the on and off switch and a value. When the switch is off, many applications ignore the value, and use their built-in default.

Flavour three: multivariate

A multivariate feature has several named variations, such as “layout A,” “layout B,” and “layout C.” Each variation is given a percentage in each environment, and Flagsmith assigns each user to exactly one variation in a stable way. This flavour powers experiments, often called A/B tests, and gradual migrations between several versions of a behaviour.

How to choose

• Start with the question. If the answer is yes or no, use a plain flag. If it is a number or text, use a value. If it is “which one of several,” use multivariate.
• Prefer simple. A plain flag is easier to reason about and test than a multivariate feature with five options.
• Do not hide a different feature inside a value. If a value changes what the application does in a large way, such as “mode equals A, B, or C,” make it multivariate or split it into separate features.
• Keep values small. Large blocks of text or data are better stored in a proper content system, with a flag pointing to which one to use.

Creating a feature takes only a minute, but the choices made in that minute shape months of work. Let us walk through the steps with care.

Naming rules that save headaches

• Describe the capability, not the project. “express_checkout” lasts longer than “q3_launch_thing.”
• Use one consistent style. Pick lower-case words joined by underscores, or hyphens, and keep it everywhere. Mixed styles make search and automation harder.
• Avoid negative names. A feature called “disable_cache” leads to confusing double negatives, such as “not disabled.” Prefer positive names like “cache_enabled.”
• Keep names stable and unique. Never reuse the name of a deleted feature for a different purpose, because old code somewhere may still react to the old meaning.
• Add a prefix for kind or team when it helps. For example, “ops_” for emergency switches, or “exp_” for experiments.

Defaults and the project-level safety setting

By default, the starting enabled state and value you choose when creating a feature may be copied into all environments. That is handy for harmless settings, but risky for new capabilities. Flagsmith offers project-level options to stop default values from being applied everywhere, and many teams prefer to keep new features off in every environment except Development. Look at your project’s settings to find the exact option and its name in your version.

The same feature behaves differently in each environment, and that difference is the main source of its power. Let us see how.

A quick reminder: what is an environment?

An environment is a separate place where your product runs, such as Development, Staging, or Production. In Flagsmith, each environment holds its own set of answers for every feature, and has its own access keys. An application chooses its environment simply by being given that environment’s key.

The ladder of states

Because states are separate, a feature can climb a ladder, one rung at a time, collecting evidence on each rung.

Notice that the name and description are identical in all three rows. Only the decisions differ. A developer who changes the Development state changes nothing in Production.

flowchart LR
    D["Development: on for all, experiment freely"] -->|"Works as intended"| S["Staging: set like next Production state"]
    S -->|"Tests pass and owners agree"| P["Production: employees, then percentage, then all"]
    P -->|"Problem found"| R["Disable in Production only"]
    R --> D
    

No automatic copying, by design

When you enable a feature in Development, nothing happens in Staging or Production. That separation is intentional, because automatic copying would defeat the safety that environments create. It does mean that someone must repeat the change in the next environment at the right moment. Teams make this step careful with reviewed requests, scheduled changes, and sometimes automatic scripts that apply the same change to the next environment after tests pass.

Why different values are healthy

A feature’s value can differ between environments for good reasons. A small number in Development makes screens easy to inspect. A realistic number in Staging tests layout and load. A cautious number in Production protects real customers. Problems begin only when differences are accidental and unexplained, a situation known as configuration drift. Compare environments before each release and explain every difference.

When one yes or no is not enough, a multivariate feature lets you offer several versions and decide how many people see each.

How a multivariate feature is built

A multivariate feature has a control value, which is the normal, current behaviour, plus two or more additional variations, each with its own value. In each environment, you assign a percentage to every variation. The control value takes whatever percentage remains. For example, you might give variation B ten percent and variation C ten percent, leaving eighty percent with the control.

How does a person get assigned?

Flagsmith needs to give each person the same variation every time they visit, otherwise a user might see a blue button on one page and a green one on the next. It does this with a technique called consistent hashing. The identity’s identifier is combined with the feature’s own identifier and fed into a mathematical scrambling function called a hash. The hash always gives the same result for the same input, but the results look random and spread evenly. The result is turned into a number from zero to one hundred, and the variations occupy slices of that range according to their percentages. Because the same user and the same feature always give the same number, the user receives a stable experience.

Mixing in the feature’s identifier matters. Without it, the same unlucky users would be in the first slice of every feature in the company, and would become permanent guinea pigs.

Running a sensible experiment

Multivariate features make A/B tests possible, but the feature only chooses the groups. The science of judging results lies elsewhere. A few rules keep the experiment honest.

• Choose the measurement first. Decide what you will measure, such as sign-ups or purchases, before the test starts.
• Do not peek and stop early. Stopping the moment one side looks better is a good way to be fooled by chance.
• Run for whole weekly cycles. People behave differently on weekends and weekdays.
• Watch guardrails. A change that raises clicks but slows pages or raises support calls may be a bad bargain.
• Send results to analytics. Flagsmith can pass information about which variation a user saw to analytics tools through integrations, so that the analysis can be done where your business numbers live.

Multivariate for gradual migrations

Multivariate features are not only for experiments. They also help move between versions of behaviour, such as three different recommendation engines. You place old and new on shares of traffic, watch the numbers, and shift the shares slowly until the old engine receives none. Then you remove the old code and the old variation.

A feature does not have to give everyone the same answer. Flagsmith lets you decide, group by group and person by person, who gets what.

Identities and traits

An identity is a user, device, or account that your application tells Flagsmith about, usually by sending a unique identifier such as a user number. A trait is a fact stored about that identity, such as country, plan, app version, or signup date. Together they let you describe who a user is without Flagsmith knowing anything else about them.

Segments

A segment is a saved group of identities defined by rules about their traits. For example, “Premium users in India” might mean plan equals premium and country equals India. Segment rules can combine several conditions, using words such as “and” and “or,” and can test whether a number is above a limit, whether a text contains a word, or whether a value is one of a list. Segment definitions belong to the project, so they have the same meaning in every environment.

Segment overrides

A segment override says, for one feature in one environment, “people in this segment get this special answer.” For example, in Production you might override the “new checkout” feature so that the “Employees” segment has it enabled, while everyone else still has it disabled. Because the override is stored inside the environment, the same segment can receive a different answer in Staging.

flowchart TB
    Q["Request: feature answer for identity 4821 in Production"] --> I{"Identity override exists?"}
    I -->|"Yes"| A1["Use the identity override"]
    I -->|"No"| G{"Matches a segment override?"}
    G -->|"Yes, highest priority wins"| A2["Use the segment override"]
    G -->|"No"| M{"Multivariate feature?"}
    M -->|"Yes"| A3["Assign variation by percentage using stable hashing"]
    M -->|"No"| A4["Use the environment default state and value"]
    A1 --> OUT["Return enabled state and value to the application"]
    A2 --> OUT
    A3 --> OUT
    A4 --> OUT
    

The order of decision

Flagsmith decides in layers, from the most specific to the most general. First it checks whether the single identity has a personal override. If not, it looks at the segment overrides that the identity qualifies for. When several segments match, a priority order that you control decides which one wins. If no segment matches, the environment’s normal state applies, with the percentage split if the feature is multivariate.

Common targeting recipes

Identity overrides: the personal touch

An identity override gives one specific identity a special answer for a feature in one environment. It is perfect for letting a single important customer try a beta, or for letting a support engineer reproduce a bug as a particular user. Use identity overrides sparingly. If you find yourself creating hundreds of them, a segment rule is almost always a cleaner solution, and the large number of overrides makes the environment data heavier.

A feature in the dashboard is only half of the story. The other half is the application that asks for it. Let us follow the question from the code to Flagsmith and back.

The SDK

An SDK, short for software development kit, is a small library that you add to your application so that it can talk to Flagsmith in your own programming language. Flagsmith provides SDKs for many languages, covering web pages, mobile apps, and back-end servers. The SDK is given the environment key when it starts, and uses it to find the right environment.

Two basic questions in code

In your code, you normally ask Flagsmith one of two simple questions, using the SDK’s methods. The first is “is this feature enabled?” which returns yes or no. The second is “what is this feature’s value?” which returns the stored value. Often you ask both at once, by requesting all the flags for the current user and then looking up the ones you need. In either case, you also provide a default, which the code uses if Flagsmith cannot answer.

sequenceDiagram
    participant U as User
    participant A as Application
    participant SDK as Flagsmith SDK
    participant FS as Flagsmith
    U->>A: Opens the checkout page
    A->>SDK: Get flags for identity 4821 with traits
    SDK->>FS: Request using the environment key
    FS->>FS: Find environment then apply identity and segment overrides
    FS-->>SDK: Enabled state and value for each feature
    SDK-->>A: Results kept in memory
    A->>A: Is new checkout enabled?
    A-->>U: Show the new or the old checkout
    

Remote versus local evaluation

There are two ways for the answer to be worked out. In remote evaluation, the SDK sends a request over the network, and Flagsmith’s servers run the rules and send back the answers for that user. This works with the public client-side key and is the normal way for browsers and mobile apps. In local evaluation, a back-end server uses its secret server-side key to download the full set of rules for the environment, called the environment document, and then works out answers itself, from memory, with no network trip for each check. Local evaluation is extremely fast and keeps working during short outages, while changes arrive at the next refresh.

Defaults: the safety net

A default is the value your code uses when Flagsmith cannot give an answer, for example during a network problem, or if the feature has been deleted by mistake. The best default is almost always the old, proven behaviour, because it protects users when anything fails. Defaults are written in your code next to the feature check, not stored in Flagsmith. Choose each one deliberately, and never let a risky new capability become the fallback.

Keeping answers fresh

Browsers and phones cannot refresh as casually as servers. A typical approach is to fetch flags at the start of a session, keep them in memory, and refresh at sensible moments, such as when the app returns to the foreground, or on a modest timer. Some SDKs can also receive updates pushed from the server, so that an emergency switch acts within seconds. Teams choose the balance between freshness and traffic, according to how critical each feature is.

Every feature is born, grows, and should eventually die. Teams that respect this life cycle keep their code clean. Teams that ignore it drown in old switches.

flowchart LR
    A["Plan: purpose, owner, expiry"] --> B["Create feature OFF everywhere"]
    B --> C["Write code for both on and off paths"]
    C --> D["Enable in Development and build"]
    D --> E["Deploy code to all environments with flag OFF"]
    E --> F["Rehearse in Staging"]
    F --> G["Gradual rollout in Production"]
    G --> H["Fully on and stable"]
    H --> I["Remove old code path"]
    I --> J["Archive then delete the feature"]
    G -->|"Problem"| K["Disable in Production and fix"]
    K --> F
    

The life cycle in words

The cost of two code paths

While a feature lives, your program carries two behaviours. That is the price of flexibility. Every live feature roughly doubles the number of ways the program can run, so ten live features mean over a thousand combinations. Nobody can test them all. This is why short lifetimes matter so much: fewer live features mean fewer combinations and less complexity.

Archive before you delete

Deleting a feature that some forgotten service still reads can cause errors, or force that service to use its default. A gentler step is to archive the feature, which marks it as no longer in use and hides it from normal lists, while keeping it available. After a safe waiting period, with the audit log and evaluation numbers showing nobody reading it, you can delete it for good.

Not every feature is the same kind of thing. They live for different lengths of time, are controlled by different people, and need different care.

Software engineer Pete Hodgson, in a widely read article hosted on Martin Fowler’s website, grouped feature toggles into four families, by how long they live and how dynamic they are. The same grouping fits Flagsmith features very well.

Release features in detail

Release features are the workhorse of continuous delivery. A team starts a new search page. On day one a developer creates a feature for it, switched off. Every small piece of the new page is merged into the main line behind this feature. Nobody sees any change. When the page is finished and tested, the feature is turned on gradually. After a few weeks at full strength, the feature and the old page code are deleted.

Experiment features in detail

An experiment feature is usually multivariate. Users are divided randomly into groups, and each group sees a different version. The team measures one agreed number, such as how many people complete a purchase, and compares groups. Because the assignment is stable and random, the team can be fairly confident that differences come from the change and not from luck.

Operational features in detail

An operational feature is like the emergency brake in a train. Suppose a recommendation panel depends on a slow external service. If that service becomes unhealthy, every page that waits for it becomes slow. An on-call engineer can disable the panel with one click, and pages become fast again without recommendations. The product degrades gracefully instead of failing. Such a switch is often called a kill switch. Because it must be dependable, its off state should be tested before an emergency, and its default should protect the system.

Permission features in detail

Permission features answer the question, “Is this person allowed to use this?” A company may give a reporting tool only to customers on its top plan. Because these decisions follow business rules rather than rollout schedules, these features tend to stay for a long time. They may be better expressed as clear product rules in some designs, but Flagsmith segments make them easy to manage when you want quick control.

A small team may have ten features. A large company may have thousands. Good organisation is what keeps the list useful and not terrifying.

Tags

A tag is a short label attached to a feature. Teams use tags to describe the area (checkout, search), the purpose (release, experiment, ops), the team that owns it, and its status (temporary, stale, do-not-remove). The dashboard can filter the feature list by tag, so a payments engineer can see only payments features, and a release manager can see all temporary ones. A small, agreed set of tags is far more valuable than a huge, messy one.

Owners

Every feature should have an owner. In Flagsmith, features can be given individual owners and group owners in many versions, so that responsibility is visible. When a feature has no owner, nobody feels responsible for turning it off or deleting it, and it quietly lives on. Make owner assignment part of the creation routine.

Descriptions as documentation

The description is the place to write what the feature does, what happens when it is off, who to contact, and when it should be removed. Treat it like a short note you leave for a stranger who will need it urgently.

Spotting stale features

A stale feature is one that has been fully on, or fully off, for a long time, and is no longer providing any safety or choice. It is dead weight. Teams find stale features by looking at how long ago each was last changed, which tags it has, and what its evaluation numbers look like. Some versions of Flagsmith offer help for this, such as marking a feature as stale, and some teams add their own script that lists features not changed for sixty days. Whichever way you do it, schedule a regular review.

A naming and tagging scheme that works

A feature can change what millions of people see in seconds. That power deserves rules about who may use it and a record of what was done.

Permissions

Least privilege means each person receives only the permissions necessary for their job. Flagsmith lets administrators grant permissions at the organisation, project, and environment levels, to individuals or to groups. At project level, permissions typically cover viewing the project, creating and deleting features, and managing segments and tags. At environment level, permissions typically cover viewing the environment, updating feature states, managing segment overrides and identities, and creating or approving change requests.

Change requests and scheduling

For environments where mistakes are expensive, a feature change can be made through a change request. Instead of changing the state directly, a person proposes the change, another person reviews and approves it, and only then does it take effect. The number of approvals required can be set per environment, depending on your plan. A scheduled change allows a state change to happen at a chosen future time, which suits coordinated launches that must start at a precise moment, such as the opening of a sale.

Versioning and history

Flagsmith keeps an audit log of changes, recording who changed what, when, and in which environment. In versions that support feature versioning, a feature’s state in an environment can have versions, so that an earlier state can be inspected or restored. When something goes wrong, the first question is always “what changed?” and the history answers it in seconds.

flowchart LR
    A["Developer proposes change in Production"] --> B["Change request created"]
    B --> C{"Reviewer approves?"}
    C -->|"No"| D["Comments and revision"]
    D --> B
    C -->|"Yes"| E["Change applied or scheduled"]
    E --> F["Audit log records who, what, when"]
    E --> G["Webhook posts to team channel"]
    E --> H["Applications receive new state"]
    

Webhooks and integrations

A webhook is an automatic message sent to another system when something happens. A common use is posting a line into a shared chat channel whenever a Production feature changes, such as “Production: instant transfer set to ten percent by Anil.” This simple habit means that when something odd happens, everyone sees what changed. Flagsmith also connects to analytics and monitoring tools, so that feature state can be recorded alongside your business and technical numbers.

Features and delivery pipelines are made for each other. Together they let teams ship small changes constantly and release them calmly.

A quick reminder about continuous delivery

Continuous Delivery means every change goes through an automatic assembly line, called a pipeline, that builds, tests, and prepares the code so it can be released at any moment. The same package moves from stage to stage. Only settings change, and feature values are some of those settings.

Deploy is not release

The most valuable idea here is that deploy and release are different events. A deploy puts code on servers, and it is a technical event handled by the pipeline. A release shows a capability to users, and it is a business event handled by changing a feature state. Flagsmith features are what make the split practical.

Trunk-based development

In trunk-based development, everyone merges small changes into one shared main line, at least once a day, instead of keeping private copies of the code for weeks. That keeps merging easy. But half-finished work will land in the main line. How can it be safe? The answer is the feature. Unfinished code sits behind a switched-off feature, travels to production in the normal pipeline, and stays invisible until the team decides to reveal it. The feature turns the main line into a safe place for unfinished ideas.

Branch by abstraction

When the change is deep inside the system, such as replacing a payment provider, a technique called branch by abstraction works well with features. The team places a thin layer, the abstraction, in front of the old component, then builds the new component behind the same layer. A feature decides which implementation the layer uses. Traffic is moved over gradually, then the old component is deleted, all inside the main line and with no long-lived branch.

A feature in the dashboard is easy to create. A feature inside code can easily become a mess. A few simple design habits keep it tidy.

Decide in one place

The most important habit is to check a feature in one place, near the top of a request, and then pass the decision inward. Imagine a feature check scattered across forty files: when the feature is finally removed, a developer must hunt down all forty places, and will probably miss one. If the check lives in one place, removing it is a small, safe job.

Hide old and new behind one interface

A very clean pattern, often called strategy substitution, is to write the old behaviour and the new behaviour as two interchangeable parts that fit the same shape. The feature decides which part the application uses. The rest of the program does not know that a feature exists. When the feature is retired, you delete one of the two parts and the decision, and nothing else changes.

Wrap the SDK

Add a thin layer of your own around the Flagsmith SDK. This wrapper gives features clear names, supplies safe defaults in one place, and lets tests replace real answers with fixed ones. If you ever change the SDK version, or move to another provider, you change one file instead of thousands of lines. There is also an open standard called OpenFeature, from the Cloud Native Computing Foundation, that defines a common way to ask for flags, and Flagsmith can be used through it.

Avoid checks inside tight loops

If you process a large list, ask for the feature once before the loop, keep the answer in a variable, and reuse it. Even fast checks add up when repeated a million times, and the code becomes harder to read.

Dark launching and shadow mode

A dark launch means running new code in production for real traffic, without showing its results to users. Facebook famously used this approach when it launched its chat system in 2008, running the new back-end code for real users before anyone could see the chat window, in order to see how the servers coped. A feature in Flagsmith makes dark launches easy: the feature controls whether the new code even runs, and a second feature, or the same one, controls whether its results are shown.

Features make releases safer, but they raise new questions for testers. How do you test something that behaves differently for different people?

The explosion of combinations

If a program has one feature, there are two possible behaviours. With two features there are four. With ten features there are one thousand and twenty-four, and with thirty there are over a billion. It is impossible to test every combination, and fortunately it is unnecessary, since most features control things that do not touch one another. The skill lies in testing the combinations that matter.

A practical approach

Making tests repeatable

An automatic test must give the same result every time it runs. A test that depends on a live feature whose state people change during the day would be unpredictable. Good setups let the test choose the answers itself, through a wrapper that supports overrides, or through a dedicated test environment with fixed values. The test says, “for this check, pretend the feature is on,” and everything else behaves normally.

Practising the kill switch

A kill switch that has never been tested is a hope, not a safety device. Teams should practise turning important operational features off in a controlled way, in Staging and occasionally in Production during quiet hours, to confirm that the product degrades gracefully. A page that crashes when recommendations vanish is a problem best discovered during practice.

Features give great power and also real costs. An honest engineer knows both sides.

Key trade-offs to decide on purpose

When not to use a feature

Not every change deserves one. A tiny text fix, a safe refactoring protected by strong tests, or a change that can easily be undone by redeploying may not need a switch. Changes that cannot be placed behind a switch, such as a database structure change that cannot work in both old and new forms, call for another approach, like making the database compatible with both old and new code first, and cleaning up afterwards.

A feature is a remote control for your product, so it deserves care in who can reach it and what information flows through it.

Protect the keys

Applications connect to Flagsmith using environment keys. The client-side key is meant for web pages and mobile apps, and is treated as public, since it can only ask for the flags of one user. The server-side key is secret, because it can download the full rules of the environment. Keep it in a secrets manager, never in a web page, a mobile app, or a code repository. Separate administrative tokens, used to change features by script, are even more powerful and must be guarded like a production database password.

Do not store secrets in feature values

A feature’s value travels to many systems. It may appear in logs, caches, and analytics tools. Passwords, tokens, and private addresses belong in a proper secrets manager. Use feature values for behaviour and harmless settings.

Privacy of user data

Identities and traits can contain personal information. Send only what the rules really need. Use opaque identifiers rather than names and email addresses, and send traits such as plan or country instead of anything sensitive. If you run Flagsmith on your own servers, personal data stays under your control, which can help with laws such as the European GDPR or India’s data protection law. If you use the hosted service, review the provider’s data handling terms and decide what to share. Local evaluation helps too, because identity details can stay inside your own servers while only rules are downloaded.

Auditing and access reviews

• Keep the audit log. Many compliance rules require proof of who approved Production changes.
• Review access regularly. Every few months, check who holds permissions in Production and remove those who no longer need them.
• Use single sign-on. Connect Flagsmith to your company sign-in so that people lose access when they leave.
• Separate duties. The person who proposes a critical change should not be the only one who approves it.
• Plan break-glass access. Define a documented emergency path to turn a feature off quickly, with extra review afterward.

Self-hosting and data location

Teams with strict rules about where data may live sometimes run Flagsmith on their own infrastructure, in a region of their choosing, behind their own network controls. The same feature design applies, but the work of updates, backups, and availability moves to the team. It is a serious decision, and the reward of control must be weighed against the effort of running the service reliably.

A rollout without measurement is like driving at night without headlights. Observability tells you whether the new capability is helping or hurting.

Three kinds of signals

Tag signals with the feature state

The most useful habit is to record which state of the feature a request ran with. Then any graph can be split into two lines: users with the capability and users without. The question “is the new checkout slower?” becomes a simple comparison of two lines, instead of an argument. Flagsmith can send feature information to analytics and monitoring tools through integrations, and many teams also add the state to their own logs. Flagsmith also offers evaluation counts for features in some plans, which show how often each feature is being read, a useful clue when you are deciding whether a feature is still in use.

Guardrail metrics

When a team begins a rollout, it writes down guardrail metrics, which are numbers that must not get worse no matter how good the new capability looks. Typical examples are error rate, response time at the slowest one percent of requests, payment success, app crashes, and support contacts. If any guardrail crosses its limit, the rollout pauses or reverses.

flowchart TB
    A["Raise feature to next step in Production"] --> B["Collect metrics for users with and without the feature"]
    B --> C{"Guardrails within limits?"}
    C -->|"Yes"| D{"Enough time and data?"}
    D -->|"No"| B
    D -->|"Yes"| E{"At 100 percent?"}
    E -->|"No"| A
    E -->|"Yes"| F["Finish and schedule cleanup"]
    C -->|"No"| G["Alarm fires"]
    G --> H["Disable feature in Production"]
    H --> I["Investigate with logs and traces"]
    I --> J["Fix and restart at a small step"]
    J --> A
    

Automatic reversal

People cannot stare at dashboards all day. Teams create alarms that notify them when a guardrail is crossed. The more advanced step is to let a script act on its own: when an alarm fires during a rollout, it calls the Flagsmith management interface and returns the feature to its previous state. This cuts the time between a problem starting and the problem ending from tens of minutes to seconds. A human should still review what happened afterwards.

Watch the plumbing too

Monitor how often SDKs fail to reach Flagsmith, how old the rules held in each server are, and how often applications fall back to default values. A rising number of fallbacks is an early warning that something is wrong between your applications and the flag service, long before users complain.

A feature check can happen on almost every request, so at the scale of a large company even a tiny delay or a rare failure matters.

Keep checks cheap

If every check needed a trip across the internet, a page with twenty features would feel slow. The standard approach is to fetch once, keep the answers in memory, and refresh in the background. Back-end servers use local evaluation so each check takes only a tiny slice of time. Browsers and apps fetch at the start of a session and reuse the results.

Designing for failure

Eventual consistency between servers

When a feature changes, servers do not all learn about it at the same instant. With local evaluation, each server updates at its next refresh. For a few seconds or minutes, some servers hold the old state and others the new. For most capabilities this is harmless. For multi-step journeys, decide once at the start and carry the decision with the session.

Mobile apps and old versions

Once an app version is installed on a phone, its code cannot change until the person updates. A feature is therefore a remote control for capabilities already inside the installed app. You can switch a faulty capability off on millions of phones without waiting for an app store review. But a feature guarding code that does not exist in older versions needs care, so rules often include a condition on the app version.

An anti-pattern is a tempting solution that causes trouble. Learn these so you can spot them in your own team.

These habits come from many teams learning the hard way. Following them saves you from most of the pain.

Best practices

• Create features switched off. Enable them deliberately, starting in Development.
• Choose clear, positive, stable names. Describe the capability, keep one naming style, and never reuse a name.
• Write a useful description. Say what it does, who owns it, what happens when it is off, and when it should be removed.
• Pick the simplest type. Use a plain flag for yes or no, a value for tuning, and multivariate only when several versions are truly needed.
• Tag and assign owners. Purpose, team, and status tags with a named owner make cleanup possible.
• Always supply safe defaults in code. The default should be the old, proven behaviour.
• Decide in one place. Check a feature once, near the entrance of a request, and pass the decision inward.
• Roll out in stages with guardrails. Employees, then a beta group, then a percentage, then everyone, watching the numbers at each step.
• Mirror Staging to the next Production state. Make the rehearsal predict the performance.
• Use segments, not piles of identity overrides. Rules scale and can be explained.
• Require review for critical Production changes. A second pair of eyes is cheap protection.
• Announce Production changes in a shared channel. Visibility makes investigations faster.
• Practise the kill switch. Nobody should see the off state for the first time during an emergency.
• Treat removal as part of the work. Delete the code first, then archive, then delete the feature.
• Wrap the SDK. One thin layer gives clear names, defaults, and test overrides.

Common mistakes

A checklist before changing a Production feature

Adopting features in a team that is just starting

It also helps to talk openly about culture. Features work best in teams where turning something off in Production is seen as a normal, healthy action and not as a failure to be hidden. If people fear blame, they will hesitate to reverse a bad change, and the greatest strength of a feature, its speed, is wasted. Teams that celebrate a quick, calm reversal, and then study it without blame, become safer over time.

The idea of separating release from deployment, and of controlling exposure in careful steps, is common to the best-known engineering organisations. Here are public lessons, followed by an illustrative story.

An illustrative story: a shopping app and its new search

The following story is an invented example, shown to tie the ideas together. A shopping company has a Flagsmith project with Development, Staging, and Production environments. A developer creates a multivariate feature called “search_ranking_engine,” with a control value, “classic,” and a variation, “smart.” It is created switched off everywhere, with a description naming the owner and an expiry date, and tagged “experiment” and “team-search.”

Patterns in all these stories

Short, clear answers to questions that beginners and experienced engineers often ask about features in Flagsmith.

You have travelled from the fear of big releases to the calm of small, reversible, measured changes. Here is everything worth remembering.

A feature in Flagsmith is a named control, defined once, that can carry a switch, a value, or several variations, with a separate and private answer in each environment and for each group of users. It lets teams deploy code early and release it later, change behaviour without releasing again, and reverse a bad decision in seconds. The practical habit to carry away is to treat every feature as a short-lived loan of safety: create it off, give it a clear name, owner, and expiry, roll it out in careful steps while watching the numbers, and then remove it once its job is done.