Before clicking anything, let us make sure the idea is clear. A flag is simpler than it sounds.

A switch outside the code

A feature flag is a named switch that lives outside your program. Your program asks a simple question, such as “is the new checkout page on?”, and the flag service answers yes or no. Because the answer comes from the service and not from the code, you can change the answer at any moment without building or releasing anything. The code contains both versions of the behaviour, the old and the new, and the flag decides which one runs.

Why teams use flags

Two flavours in Flagsmith

Flagsmith treats a feature as having two parts that can be used together or separately. The first part is the enabled state, which is simply on or off. The second part is an optional value, which can be text, a number or a small piece of structured data. A feature used only for its on or off state is a plain flag. A feature used mainly for its value is often called remote configuration. A single feature can use both, for example “the banner is enabled, and its message says Welcome back.”

Let us get to know the tool before we use it.

What Flagsmith is

Flagsmith is a feature flag and remote configuration service. It gives you a web dashboard where people manage flags, and it gives your applications small code libraries, called SDKs, that ask Flagsmith for the current state of each flag. An SDK, short for software development kit, is a ready-made helper for a particular language or platform, so you do not have to write the network requests yourself. There are SDKs for web pages, mobile apps and many server languages.

Hosted or self-hosted

You can use the hosted service, where the Flagsmith team runs everything and you simply sign in, or you can run the open-source software yourself on your own servers. For a first flag, the hosted service is the quickest path, because there is nothing to install. Everything in this guide applies to both, apart from the sign-up and the address your applications use to reach the service.

The two kinds of traffic

It helps to picture two streams. The first is people using the dashboard to create and change flags. That stream is small and human. The second is applications asking what each flag should be for each user. That stream can be large, because a busy product asks all day long. Creating your first flag is about the first stream, and connecting your application is about the second.

Flagsmith arranges everything in layers. Learning them first makes every later screen make sense.

The layers

At the top is the organisation, which usually represents your company or team. It holds the people, the billing and the overall history. Inside an organisation live projects. A project usually represents one product or application, such as your website or your mobile app. Inside a project live environments. An environment is a separate copy of the world, such as development, staging and production. Inside the project you also define features, which are your flags and configuration values. Each environment keeps its own state for every feature.

flowchart TB
    O["Organisation: Your Company"] --> P1["Project: Website"]
    O --> P2["Project: Mobile App"]
    P1 --> E1["Environment: Development"]
    P1 --> E2["Environment: Staging"]
    P1 --> E3["Environment: Production"]
    P1 --> F["Features defined once for the project"]
    F --> F1["Feature: new_checkout"]
    F --> F2["Feature: welcome_banner"]
    E1 --> S1["new_checkout is ON"]
    E2 --> S2["new_checkout is ON"]
    E3 --> S3["new_checkout is OFF"]

Reading the picture

The organisation at the top contains two projects, a website and a mobile app. Looking at the website project, you see three environments and a list of features. The important idea is on the right: a feature such as new_checkout is defined once for the project, but each environment stores its own on or off state for it. In the picture, the new checkout is on in development and staging, where the team tests it, and off in production, where customers are. This is the safety that makes flags useful.

Why environments matter so much

Environments let you try things safely. You create a flag, switch it on in development, test the behaviour, repeat in staging and only then switch it on in production. Mistakes made in development hurt nobody. Production stays calm until you decide otherwise. Many beginners underestimate this, and then learn it the hard way the first time they change something live by accident.

Five minutes of thinking now saves hours of confusion later. Decide these things before you click the button.

Choose something small and safe

Your first flag should be easy to understand and harmless to get wrong. A good example is a welcome banner on a test page, a small new button or a non-critical message. Avoid choosing something tied to payments, security or data deletion for your very first attempt. The goal is to learn the workflow, not to take risks.

Decide the question the flag answers

Write the flag’s purpose as a short question that has a clear yes or no answer, for example “Should this user see the new welcome banner?” If you cannot phrase it that way, the idea may be too vague. A flag that tries to control many things at once becomes hard to reason about.

Pick a good name

The name is how your code and your colleagues refer to the flag, so it must be clear. Good names are short, descriptive and consistent. Many teams use lowercase words joined by underscores, such as welcome_banner. Avoid names like test1 or new_thing, which tell nobody anything after a month. Avoid putting a date or a person’s name in the flag. A name that describes the behaviour stays useful longer.

Decide who owns it and when it ends

Every flag should have an owner, the person responsible for it, and an expected end date. Most flags are meant to be temporary: once a feature is fully released and stable, the flag should be removed along with the old code path. Flags that never die pile up and make the code harder to understand. Writing the owner and the plan in the description from the start prevents this.

Before a flag can exist, it needs a home. Here is how to create one from nothing.

Choosing names that last

Names of organisations, projects and environments appear everywhere: in the dashboard, in logs and in conversations. Pick clear, boring names. Avoid clever names that only you understand. Keep the environment names consistent across all your projects, so that “production” always means the same thing.

Inviting teammates

Flagsmith lets you invite colleagues and give them roles. Early on, you might be tempted to share one login. Please do not. Individual accounts give you a trustworthy history of who changed what, and let you remove access cleanly when someone leaves. Features such as finer roles and single sign-on may depend on your plan or edition, so check what is available to you.

This is the heart of the guide. Follow these steps slowly, and notice the choice at each one.

What just happened

You created a feature, and Flagsmith placed it in every environment of the project, each with its own state. The state you chose in the form applies to the environment you were in when you created it, and other environments typically start with the default state. Open the production environment and look at your new feature. Confirm that it is disabled there. This habit of checking the other environments after a change will serve you for years.

The fields explained

Your flag exists. Now let us learn to control it, safely and with confidence.

The toggle

Next to each feature in the list for an environment, you will find a toggle, a small switch that shows the current state. Click it to turn the feature on or off for that environment. In most versions you are asked to confirm the change. Once confirmed, the new state is saved immediately, and applications asking for the flag will receive the new answer the next time they ask, or the next time their cached copy refreshes.

How quickly does a change take effect?

The dashboard saves the change at once. How soon an application notices depends on how that application’s SDK is set up. Some ask the service on every request and notice immediately. Others keep a cached copy for a short time to reduce traffic and refresh it at intervals, so the change appears within that interval. Some server setups use local evaluation, where rules are downloaded and refreshed periodically. Understanding this stops you from panicking when a change does not appear in the same second.

sequenceDiagram
    participant P as Person in Dashboard
    participant F as Flagsmith Service
    participant S as Application SDK
    participant A as Your Application
    participant U as User
    P->>F: Turn welcome_banner ON in Development
    F->>F: Save new state and record in audit log
    F-->>P: Change confirmed
    U->>A: Opens the home page
    A->>S: Is welcome_banner on for this user
    alt SDK holds a fresh cached answer
        S-->>A: Returns cached answer
    else Cache expired or empty
        S->>F: Ask for current flags
        F-->>S: Returns latest state
        S-->>A: Returns new answer
    end
    A-->>U: Shows the page with or without the banner

Reading the sequence

At the top, a person turns the flag on in the development environment. Flagsmith saves the new state, writes an entry in its audit log and confirms to the person. Later, a user opens the home page. The application asks its SDK whether the banner is on. If the SDK holds a fresh cached answer, it replies instantly with whatever it last learned. If the cached answer has expired or is empty, the SDK asks Flagsmith for the latest state and passes the new answer back. The page is then shown with or without the banner.

Good habits when switching

• Confirm the environment name every single time you click.
• Change one thing at a time, so you know what caused any effect.
• Tell your team in a chat channel when you change something in production.
• Watch your monitoring for a few minutes after turning on a significant flag.
• Know in advance how you will turn it off, and who will do it.

A flag can do more than say yes or no. It can carry information, and that makes it a remote control for your application’s settings.

What a value is

Besides its on or off state, a feature can hold a value. A value can be a short piece of text, a number, or structured data in a common format. Your application reads the value and uses it. For example, the welcome banner feature could carry the message text, so that marketing can change the wording without waiting for a release. Another feature might carry a number, such as the maximum number of items shown in a list, so that engineers can tune it as they watch performance.

Flag state and value together

The two parts are independent but can be combined. The state controls whether the feature is active, and the value controls how it behaves when active. A well-designed feature often has both: the banner is enabled, and its message reads whatever the value says. If the feature is disabled, your application ignores the value and behaves as if the banner does not exist.

Cautions about values

• Never store passwords, keys or other secrets in a value. Values can appear in logs, in client applications and in webhook messages.
• Remember that values read by browsers and mobile apps are visible to anyone who inspects the traffic.
• Validate values in your application, so a typing error in the dashboard cannot break a page.
• Keep values small and clear. Large or complicated values become hard to review and risky to edit.

A flag in the dashboard does nothing until an application asks about it. This chapter explains how the connection works, without any code.

Environment keys

Each environment has keys that applications use to identify which environment’s flags they should read. A client-side key is designed for browsers and mobile apps and is safe to include in them, because it can only read flags. A server-side key is for trusted servers and unlocks additional abilities, such as local evaluation. Server-side keys must be kept secret. Find the keys in the environment’s settings, copy the correct one for the type of application you are building and store it in your application’s configuration, not in public code.

Choosing an SDK

Flagsmith offers SDKs for many platforms. Choose the one that matches the language or platform of your application. Installing it follows the normal process for that platform, and the documentation lists the exact steps. In every case, you give the SDK the environment key and, if you self-host, the address of your installation.

The four things every application does

Defaults protect you

Networks fail, services restart and requests time out. Your application must decide what to do when it cannot get an answer. The best practice is to define a default for every flag in your code. For a new feature the safe default is usually off, so a failure simply hides the new behaviour. Test this by deliberately blocking access to Flagsmith in a development environment and watching what your application does.

A flag is only trustworthy when you have watched it work. Here is a simple test routine you can repeat for every flag you ever create.

flowchart TD
    A["Create flag disabled in Development"] --> B["Run app and confirm old behaviour appears"]
    B --> C["Switch flag ON in Development"]
    C --> D{"New behaviour appears after refresh"}
    D -- No --> E["Check key, environment, name spelling and cache"]
    E --> B
    D -- Yes --> F["Switch flag OFF again and confirm old behaviour returns"]
    F --> G["Block access to Flagsmith and confirm safe default"]
    G --> H["Repeat the routine in Staging"]
    H --> I["Release to Production with flag still OFF"]
    I --> J["Turn ON gradually and watch monitoring"]

Reading the routine

Start with the flag disabled in development and confirm that your application shows the old behaviour. Switch the flag on, refresh and confirm that the new behaviour appears. If it does not, work through the usual suspects: the wrong key, the wrong environment, a misspelled name or a cached answer. When it works, switch the flag off again and confirm that the old behaviour returns. Many people forget this step, and discover too late that turning a flag off does not actually restore the old state.

Next, test the failure case. Block your application’s access to Flagsmith, and confirm that it falls back to the safe default and keeps working. Then repeat the routine in staging. Finally, release the code to production with the flag still off, confirm that nothing changed for users, and turn the flag on gradually while watching your monitoring.

If the flag does not seem to work

So far your flag is on or off for everybody. The real power appears when you decide who sees what.

Identities

An identity is one particular user known to Flagsmith, identified by an ID that your application supplies, such as a user number. When your application asks for flags on behalf of an identity, Flagsmith can give that person different answers from everyone else. You can override a flag for a single identity, which is perfect for letting one colleague or one customer see a feature early.

Traits

A trait is a small fact about an identity that your application sends, such as plan type, country or app version. Traits are the raw material for targeting. They let you say things like “show this to users on the premium plan” without naming every person.

Segments

A segment is a saved group of users defined by rules on their traits. For example, a segment called beta testers might include everyone whose trait says they joined the beta programme. Once defined, a segment can be reused across many flags. In a feature’s settings, you add a segment override, which says “for this segment, give this flag a different state or value from the default.”

A typical rollout path

Instead of a risky switch from nothing to everything, you can turn a flag up like a volume knob.

Percentage rollouts

A percentage rollout enables a feature for a chosen share of users. Flagsmith assigns each user a stable position, so the same user keeps getting the same answer as you raise the percentage. A user in the first five percent stays in as you move to ten percent. This matters because a feature that appears and vanishes for the same person would feel broken.

How to ramp up

A careful ramp might go from internal staff, to one percent, five percent, twenty-five percent, half and then everyone, pausing at each step to look at errors, speed and business measures. If anything worsens, you stop or step back down. The pace depends on your risk. A cosmetic change can ramp quickly. A change to payments deserves a slow climb.

Multivariate options and experiments

Beyond simple on and off, Flagsmith supports multivariate features, where a flag has several possible values with a share of users assigned to each. This lets you compare variations, for example three different banner messages, and see which performs better using your own analytics. Flagsmith handles the assignment, and your analytics tool measures the result. Experimentation needs care to interpret correctly, so start with the basics before trying it.

Ten flags are easy to manage by memory. Two hundred are not. Good habits at the start keep a growing collection tidy.

Naming conventions

Agree a naming style with your team and use it every time. A consistent style might be lowercase words joined by underscores, beginning with the area of the product, for example checkout_new_payment_form. Descriptive names help people search and understand. Avoid abbreviations that only one person knows, and avoid negative names such as disable_old_search, which make on and off confusing. A flag called new_search that is on means the new search is active, which is easy to read.

Descriptions that help

The description should answer four questions: what does it control, who owns it, when was it created and when should it be removed? A sentence or two is enough. In a year, when somebody wonders whether a flag is still needed, the description is the first and often the only clue.

Tags for grouping

Tags are short labels attached to features. Use them for dimensions you will want to filter on, such as the team, the type of flag or the related project. Keep the set of tags small and agreed, because tags that multiply without control lose their value. Some useful tag ideas are release, experiment, kill-switch and permanent.

Flag lifetimes

It helps to tell people what kind of flag each one is. Release flags exist to roll out a feature and should be short lived. Experiment flags exist to test ideas and end when the test ends. Kill switches exist to turn things off in emergencies and may live long. Permission or plan flags control access to paid features and may be permanent. Labelling the kind makes it clear which flags should be cleaned up and which should be kept.

A flag has a life: it is born, used, finished and, ideally, removed. Understanding the whole cycle keeps your system clean.

flowchart LR
    A["Plan: purpose, owner, end date"] --> B["Create: disabled in all environments"]
    B --> C["Build: code with both paths and a safe default"]
    C --> D["Test: dev then staging"]
    D --> E["Release code with flag OFF"]
    E --> F["Roll out: individuals, segments, percentages"]
    F --> G["Full on: monitor for a safe period"]
    G --> H["Clean up: remove flag and old code path"]
    H --> I["Archive the flag in Flagsmith"]

Reading the lifecycle

The cycle begins with a plan: the purpose, an owner and a planned end. The flag is then created, disabled in every environment, and the code is written with both paths and a safe default. Testing happens in development and staging. The code is released to production with the flag still off, so the release itself changes nothing for users. After that, the rollout begins, first for individuals, then for segments and percentages, until the flag is on for everyone. Then there is a safe period in which you watch for trouble. Finally comes the step many teams skip: cleanup, where the flag is removed from the code along with the old path, and the flag is archived in Flagsmith.

Why cleanup matters

Every flag left in the code is a branch that someone must understand. Over time, forgotten flags make the code confusing, make tests more complex and hide bugs in rarely used paths. Teams that never clean up find themselves afraid to touch old flags because nobody remembers what they do. Make cleanup part of the definition of done for any feature that used a release flag.

Archiving

Flagsmith lets you archive a feature that is no longer needed, which removes it from the active list while keeping the history. Archive only after the code no longer asks for the flag, otherwise applications will receive unexpected answers. A good routine is to remove the code first, deploy, confirm nothing asks for the flag, and then archive it.

A flag is a powerful lever, so it matters who can pull it, and who can see who pulled it.

Who should be allowed to change what

Not everyone needs the power to change production flags. A common arrangement lets many people view flags, a smaller group change flags in development and staging, and an even smaller group change them in production. Flagsmith supports roles and permissions at several levels, though the finer controls may depend on your plan. Set these up early, while the team is small and the habit is easy to build.

Change approval and scheduling

Some editions offer change requests, where a flag change in a sensitive environment must be approved by another person before it takes effect, and scheduling, where a change is set to occur at a chosen time. These features add a second pair of eyes and let you prepare changes calmly in advance. If they are available to you, consider turning them on for production.

The audit log

The audit log is Flagsmith’s diary. It records who changed what and when, for flags, segments and settings. It answers the most common question in any incident: what changed recently? Make a habit of checking it first when something unexpected happens. Some plans allow the log to be sent onward to other systems through webhooks, which is useful for compliance and for chat notifications.

Flags look harmless, but they control what your product does. A few simple habits keep them safe.

Protect the keys

Server-side keys can read configuration that you may not want public, and they enable local evaluation. Keep them in a secrets manager or protected configuration, never in code repositories, public pages or chat messages. Client-side keys are designed to be visible in browsers and apps, but they should still be tied to the correct environment, and you should never place secrets in values read by clients.

Protect the dashboard

Give each person an individual account, use strong passwords, enable multi-factor authentication if it is offered and use single sign-on if your plan includes it. Review the user list regularly and remove people who have left or changed roles. Limit who can change production.

Minimise personal data

If you use identities and traits, send only what is needed. Use opaque identifiers instead of names and email addresses, and avoid sensitive information in traits. Smaller data means smaller risk, and simpler privacy reviews.

Do not hide secrets in flags

Never store passwords, tokens or private keys in flag values. Values can travel in network responses, appear in logs and be included in webhook messages. Flags are for behaviour and non-sensitive settings.

A flag service sits close to the heart of your product. These habits make sure it helps and never hurts.

Ask less often

Every flag question that leaves your application costs a little time and adds a little load. Good SDK settings reduce this. Caching keeps recent answers in memory for a short time. Local evaluation, available on server-side SDKs, downloads the rules and decides flags inside your own server, so most questions never touch the network. Choose refresh intervals that match how quickly you need changes to appear.

Expect the service to be briefly unavailable

No service is perfect. Design your application so that a flag outage does not become your outage. Set defaults in code, use short timeouts so a slow answer never makes a page slow, and let SDKs keep the last known answers. Test the failure on purpose.

Keep flag checks cheap and few

Avoid asking about the same flag many times in a single request. Read it once and reuse the answer. Avoid wrapping tight loops with flag checks. Keep the logic around a flag simple, because complicated branching makes behaviour hard to predict and test.

Almost everyone makes the same handful of mistakes at the start. You can skip them by knowing them in advance.

Let us put everything together by following an imaginary team through the creation, testing and release of one small flag.

The team and the idea

A small online bookshop wants to add a welcome banner to its home page, offering free delivery on a first order. The marketing team wants to change the wording and switch the banner off after a campaign. The developers want to release the code early without showing the banner until marketing is ready. A flag is the perfect tool.

Planning

The team decides the question: should this visitor see the welcome banner? They name the flag welcome_banner, write a description with the owner and an expected end date, and agree that the safe default in code is off. They also decide that the message text will be stored as the flag’s value, so marketing can edit it without a release.

Creating and building

In the development environment, a developer creates the feature, leaves it disabled, enters a placeholder message as its value and adds a tag showing it is a release flag. The code is written so that if the flag is on, the banner appears with the stored message, and if it is off or unavailable, nothing changes. They test with the flag off, then on, then off again, and finally with Flagsmith blocked.

Rolling out

sequenceDiagram
    participant D as Developer
    participant M as Marketing
    participant F as Flagsmith
    participant S as Shop Website
    participant V as Visitors
    D->>F: Create welcome_banner, disabled in all environments
    D->>S: Release code with banner path and safe default off
    S-->>V: Site looks exactly as before
    M->>F: Enter final message text as the value in Production
    M->>F: Enable for internal staff segment only
    S-->>V: Staff see the banner, everyone else does not
    M->>F: Raise rollout to 25 percent of visitors
    S-->>V: A quarter of visitors see the banner
    M->>F: Enable for everyone
    S-->>V: All visitors see the banner
    M->>F: Campaign ends, switch the flag off
    S-->>V: Banner disappears with no release
    D->>S: Remove banner code and flag check later
    D->>F: Archive welcome_banner

Reading the story

At the top, the developer creates the flag and ships the code with the flag off. Visitors notice nothing, which proves that the release itself was safe. Marketing then enters the final message and enables the banner for the internal staff segment, so colleagues can check it on the real site. After that, marketing raises the rollout to a quarter of visitors, watches the numbers and finally enables it for everyone. When the campaign ends, one click removes the banner from the site without any release. Later, the developer removes the dead code and archives the flag.

What went well

When your flag does not behave, work through these questions in order. Most problems are simple.

Which user are you testing as?

A frequent source of confusion is that the answer depends on who is asking. If you added an identity override or a segment rule, the answer for your test user may differ from the answer for a different user. When results look strange, check which identity the application is sending and what overrides apply to it. The dashboard lets you look at an identity and see exactly what Flagsmith would return for it.

A compact list of habits that keep flags useful for years instead of turning into clutter.

Measure the health of your flags

A few simple counts reveal whether your flags are healthy. How many flags exist? How many are older than their planned end date? How many have no owner or description? How many have been fully on or fully off for months? Review these numbers each quarter and clean up what no longer earns its place. A tidy collection of flags is a sign of a disciplined team.

Feature flags are not a new idea. Many famous companies have used them for years, and their experience offers useful lessons.

Your first flag is the start of a journey. Here is a sensible path for learning more, one step at a time.

The flag you create in the dashboard is the same everywhere, but the way an application uses it depends on where the application runs.

Websites in the browser

A page running in a visitor’s browser is visible to that visitor. Anyone can open the developer tools and inspect what the page receives. For this reason, browser applications use the client-side key and receive only the flags and values meant for display. Because every page view may need an answer, browser applications benefit from caching and from keeping the number of flag questions small. A common approach is to fetch all the flags once when the page loads and then read them from memory as needed.

Mobile apps

Mobile apps live on people’s phones, and different people run different versions. A flag that works for your newest release must also behave sensibly for a version released six months ago. Mobile apps often have unreliable connections, so they depend even more on cached answers and safe defaults. Many teams store the last known flag values on the device, so that the app can start instantly and update in the background. Because old versions can linger, be careful about removing flags that old versions still ask for.

Server applications

Servers are trusted places that you control, so they can use the server-side key and take advantage of local evaluation. With local evaluation, the server downloads the flag rules and decides answers itself, so most questions never touch the network. A server may serve thousands of users at once, so it must pass the right identity to each question, because different users can receive different answers. Servers should also be prepared for rolling restarts and brief network failures.

Background jobs and scheduled tasks

Flags are not only for user interfaces. A nightly job might use a flag to switch between an old and a new way of processing data. Because jobs run without a person watching, extra care is needed. Log which flag state a job used, so you can explain its results later, and avoid changing a flag in the middle of a long-running job unless the job is designed to handle it.

A flag doubles the number of paths through your code. Good testing habits make sure both paths keep working.

Two paths, two sets of checks

Every flag creates at least two behaviours: the old one and the new one. A change that works only when the flag is on, or only when it is off, is a trap. Your automated tests should confirm that the application behaves correctly with the flag off, which is the existing behaviour that must not break, and with the flag on, which is the new behaviour you are building. As flags multiply, the number of combinations grows, so keep each flag focused and avoid unnecessary connections between flags.

Controlling flags in tests

Tests should not depend on a live flag service or on the current dashboard state. A test that passes today and fails tomorrow because someone changed a flag is worse than useless. Instead, tests should supply the flag state directly, using a simple replacement for the SDK that returns whatever the test needs. This is another reason to route all flag reads through one small wrapper: in tests, you replace that single wrapper, and every flag check behaves as the test requires.

Testing the fallback

Include a test that simulates the flag service being unavailable and confirm that the application uses its safe default. It is a quick test to write and it catches a whole family of production surprises.

Testing in real environments

Beyond automated tests, use your development and staging environments in Flagsmith for end-to-end checks. A test environment with realistic flag settings can reveal problems that isolated tests miss, such as a misspelled name or the wrong key. Some teams keep a dedicated project or environment for automated end-to-end tests, with flags set to known values, so that the tests do not interfere with the work of others.

A flag’s journey from development to production should be deliberate and repeatable. This chapter shows how to keep environments in step.

The usual path

Most teams move a feature through development, staging and production. In development, engineers experiment freely. In staging, the team checks the feature in conditions that resemble production. In production, real users arrive. Each environment has its own state for the flag, so you change them one at a time as confidence grows. The danger is drift: staging and production slowly differ in ways that nobody remembers, and tests in staging stop predicting what will happen in production.

Keeping environments aligned

To limit drift, use the same flag names in every environment, and make a habit of looking at the environments side by side before a release. Flagsmith provides ways to compare environments and, depending on your plan, to copy settings from one environment to another. Where the management interface is available, teams sometimes script the creation of flags and their initial states so that every environment starts consistently.

Order of operations for a release

Why the flag must exist before the code

If code is deployed that asks for a flag that does not yet exist, the application receives no answer for it, and your default value takes over. That may be harmless, but it may also hide a mistake, such as a misspelled name. Creating the flag first, then deploying, removes this uncertainty and lets you confirm the connection before any user is involved.

Flags are cheap to create and surprisingly costly to forget. This chapter explains flag debt and how to keep it small.

What flag debt is

Technical debt is the accumulated cost of shortcuts in software. Flag debt is the share of that cost caused by flags that have outlived their purpose. Each stale flag leaves behind code branches that nobody needs, tests that check behaviours nobody uses and questions that nobody can answer. A new engineer reading the code must work out which branch is real. A bug fix must be made in both branches. A dashboard full of unknown flags becomes something to fear.

How flag debt grows

Debt grows quietly. A flag is created for a release and the release succeeds. Everyone celebrates, moves on to the next project and forgets the cleanup. The flag stays on for everyone, but the code still contains the old path. Multiply this by dozens of releases and a year, and the code is full of dead branches.

How to keep it small

Spotting stale flags

• The flag has been on for everyone for many weeks with no problems.
• The flag has been off everywhere for a long time, and the feature seems abandoned.
• The owner has left the company or changed teams.
• The description is empty or says nothing useful.
• Nobody can explain what happens if the flag is switched.

When an application asks about a flag for a user, Flagsmith follows a clear order of rules. Knowing the order removes most of the mystery from unexpected results.

The order of precedence

Imagine several rules that could apply to the same user and the same flag. Flagsmith resolves them from the most specific to the most general. First it checks whether an override exists for that exact identity. If one exists, it wins. If not, Flagsmith checks the segments that the user belongs to, and uses a segment override if there is one. When several segments match, a priority order decides which one applies. If no segment override applies, Flagsmith checks whether a percentage rollout or multivariate split gives this user a particular value. Finally, if nothing else applies, the answer is the default state and value set for the environment.

flowchart TD
    A["Application asks about a flag for a user"] --> B{"Identity override exists"}
    B -- Yes --> R1["Return the identity's own state and value"]
    B -- No --> C{"User matches a segment with an override"}
    C -- Yes --> R2["Return the highest priority matching segment's state and value"]
    C -- No --> D{"Percentage or multivariate split applies"}
    D -- Yes --> R3["Return the value assigned to this user's bucket"]
    D -- No --> R4["Return the environment default state and value"]
    R1 --> Z["Answer sent to the application"]
    R2 --> Z
    R3 --> Z
    R4 --> Z

Reading the decision

The first question is the narrowest: has someone set a special rule for this exact person? If so, nothing else matters. The second question is broader: does the person belong to a group with a special rule? The third question introduces fairness across the population: has this person been placed in a bucket by a percentage or a split? The last box is the fallback: what everybody else gets. Because the most specific rule always wins, you can make a single exception without disturbing anyone else, and you can predict the result of any combination of rules by walking down the chart.

Why this explains most surprises

Stable identities matter

Percentage rollouts and overrides depend on recognising the same user each time. If your application sends a different identifier on every visit, such as a random value generated at each page load, the user may land in different buckets and see the feature appear and disappear. Use a stable identifier, such as an internal user number, and for anonymous visitors consider a stable random identifier stored on the device.

Flags are not only a tool for engineers. When used well, they give many teams a safe way to take part in releases.

Product managers

Product managers decide what to release and to whom. Flags let them request a gradual rollout, observe the effect and decide the next step without waiting for a deployment. They can preview a feature in production using an identity or a segment, show it to stakeholders and prepare a launch for a particular day. The key discipline is to agree with engineering which flags product people may change, and which are reserved for engineers.

Marketing and content teams

When values carry text and settings, marketing teams can adjust banners, labels and promotions without a release. This turns a request that used to take days into one that takes minutes. To keep this safe, limit the editable values to those designed for it, validate them in the application and keep production changes visible to the wider team through notifications.

Support and operations teams

During an incident, support and operations teams often need to switch off a troublesome feature quickly. A kill switch flag, with clear instructions on when and how to use it, puts that power in the right hands. Operations teams can also use flags to protect the system during traffic spikes by disabling expensive, non-essential features temporarily. Practice makes this reliable, so rehearse it before you need it.

Sales and customer success teams

Sometimes a customer needs early access or a special arrangement. An identity or segment override makes this possible without special code. Record who requested it and why in the description or in your ticket system, so that the arrangement can be reviewed and ended properly.

Communicating about flags

Flags work best when everyone speaks about them in the same way. Use the flag name in tickets, release notes and chat messages, so there is no ambiguity about what changed. Post production changes in a shared channel with the flag name, the environment, who changed it and why. A short, consistent message takes ten seconds and saves many confused conversations.

When you create your next flag, you will not want to reread a whole guide. Keep this page nearby and follow it in order.

Before you click

• Write the question the flag answers in one sentence with a clear yes or no.
• Choose a short, descriptive, lowercase name and agree it with your team.
• Name an owner and a planned removal date, and write both in the description.
• Decide the safe default behaviour for when Flagsmith cannot be reached.

While creating

• Check that the environment shown is development, not production.
• Create the feature disabled, with a clear description and any agreed tags.
• Add a value only if you truly need remote configuration.
• Open the other environments and confirm the flag is disabled there too.

While building and testing

• Route every flag read through your wrapper and define the default in code.
• Test with the flag off, on, off again and with Flagsmith unreachable.
• Repeat the routine in staging before touching production.

While releasing

• Deploy the code with the flag still off and confirm nothing changed for users.
• Enable for individuals or a segment first, then a small percentage, then everyone.
• Tell the team about each production change and watch errors, speed and behaviour.
• Know exactly how to turn the flag off and who will do it.

After the release

• Leave the flag on for a safe period and watch for problems.
• Remove the flag check and the old code path, and deploy.
• Confirm no running version still asks for the flag, then archive it.

Every important word used in this guide, in plain language, for quick lookup.

Short answers to the questions beginners ask most often.

Everything in this guide comes down to a handful of ideas you can carry into your first flag and every flag after it.

A feature flag is a switch outside your code, and Flagsmith is the control desk where you manage it. Creating your first flag is simple: plan its purpose, name it clearly, create it disabled, test it in development, connect an application with a safe default and switch it on carefully. The habits around the flag matter more than the clicks. Plan the owner and the end date, test in every environment, release gradually, watch the results and clean up when you are done.