Before learning how Flagsmith does it, let us feel the problem that environments solve. It is the problem of trying things safely.

The danger of one shared switchboard

Suppose a team uses feature flags but keeps only one set of switches. Every flag has just one value: on or off. A developer working on a new checkout page turns the flag on to test it. But the same switch is read by the real website, so thousands of real customers suddenly see a half-finished checkout page. The developer meant to test, yet the world was affected.

To avoid this, the team might promise never to touch the switches carelessly. But promises are weak protection. People get tired, people misread a screen, and people click the wrong button. A safe system should not depend on perfect humans. It should make the dangerous mistake difficult in the first place.

What we really want

The team wants several separate places where code can run, each with its own private switches, so that testing in one place can never leak into another. These separate places are called environments. In each one, the same features exist, but the settings may differ: fully on in the practice hall, half on in the rehearsal hall, and still off in the main auditorium.

A short story of a Friday mistake

Meera is a developer at a travel booking company. On a Friday afternoon she wants to test a new discount banner. Her company uses a single flag list with no environments. She flips the banner flag on. Within a minute, customers see a banner promising a discount that does not exist yet. The support team gets forty calls. Meera switches the flag off and spends the weekend worrying. The next Monday the team creates separate environments. From then on, Meera flips flags in development as much as she likes, and production simply never hears about it.

The word environment is used all across software delivery. Understanding the general idea first makes the Flagsmith version easy.

What is an environment?

An environment is a separate, self-contained copy of a system where code can run. It has its own servers, its own database, its own settings, and its own secrets. What happens in one environment does not change another. The most common ones are listed below.

The golden rule: same code, different settings

A famous guideline from the “twelve-factor app” way of building software says that the code should stay the same in every environment, while only the settings change from one environment to the next. The very same packaged build is moved from development to staging to production. The things that differ are database addresses, secret passwords, and, importantly for us, the values of feature flags.

This is why environments and feature flags fit together so naturally. A flag is a setting that can change behaviour without changing code. An environment is a container that holds one complete set of such settings. Put together, they let the same build behave differently in different places, in a controlled way.

Configuration drift: the quiet enemy

When environments are set up by hand, they slowly become different from each other in ways nobody planned. A setting is changed in staging and forgotten in production. This is called configuration drift. Drift is dangerous because a test that passed in staging may not mean anything for production, since the two are no longer alike. A good environment system makes differences visible and deliberate. We will see how Flagsmith helps with this later.

Why feature flags need their own environments

Infrastructure environments, meaning separate servers and databases, already exist in most companies. But the flag values need their own separation, for three reasons. First, flag values are changed far more often than servers, sometimes many times a day. Second, product managers and support staff, not only engineers, may change them. Third, a flag value can change what millions of people see in seconds. Because of this speed and reach, each environment needs its own flag values, its own access keys, its own permissions, and its own history.

To understand where an environment sits, we first need a quick tour of the whole platform and the family tree of its parts.

What is Flagsmith?

Flagsmith is a platform for feature flags and remote configuration. A feature flag is a switch that turns a feature on or off without releasing new code. Remote configuration means storing values, such as a number or a piece of text, that your application reads while running, so you can change them without redeploying. Flagsmith is open source, which means its code is public and anyone may read it. You can use the hosted service run by the Flagsmith company, or you can run Flagsmith on your own servers.

The family tree: organisation, project, environment

Flagsmith arranges everything in a tree with three main levels.

flowchart TB
    ORG["Organisation: the company"] --> P1["Project: Shopping App"]
    ORG --> P2["Project: Admin Portal"]
    P1 --> F["Shared definitions: features, segments, tags"]
    P1 --> E1["Environment: Development"]
    P1 --> E2["Environment: Staging"]
    P1 --> E3["Environment: Production"]
    E1 --> S1["Own feature states and overrides"]
    E2 --> S2["Own feature states and overrides"]
    E3 --> S3["Own feature states and overrides"]
    E1 --> K1["Own access keys"]
    E2 --> K2["Own access keys"]
    E3 --> K3["Own access keys"]
    

The other main words you will meet

An environment in Flagsmith is a named container, inside a project, that stores one complete and independent set of feature settings, together with the keys and rules that go with them.

The simplest definition

If a project says which features exist, an environment says what is true about those features right now, in one particular place. Two environments in the same project contain the same feature names but may hold different answers. For example, the feature “new checkout” might be enabled in development, enabled for ten percent of people in staging, and disabled in production.

What lives inside an environment

An environment is not just a label. It is a bundle of several things, and each of them is separate from the other environments.

flowchart LR
    ENV["One environment, for example Production"]
    ENV --> A["Feature states: enabled or disabled and value"]
    ENV --> B["Segment overrides: special answers for groups"]
    ENV --> C["Identity overrides and stored traits"]
    ENV --> D["Environment keys: client and server"]
    ENV --> E["Settings: name, description, approvals"]
    ENV --> F["Permissions: who may view and change"]
    ENV --> G["Audit history and webhooks"]
    ENV --> H["Integrations: analytics and monitoring"]
    

The default environments

When a new project is created in Flagsmith, it normally starts with two environments, commonly named Development and Production. You can rename them, add more, and delete ones you do not need. Two is a sensible beginning, but most teams that deliver software every day end up with at least a third one, usually staging or test, placed between them.

A concrete picture

Let us imagine a project called “Shopping App” with a feature named “new checkout.” The table below shows how the same feature can look in each environment at the same moment.

Notice that the feature definition, its name, and its description are the same everywhere. Only the decisions differ. A developer who changes development changes nothing in production.

Knowing what is shared and what is separate is the key to using Flagsmith without surprises. Let us sort the main things into two boxes.

Why this split is clever

Because features are defined once, every environment always has the same list of features. A developer cannot accidentally create a feature in development that production has never heard of. When a new feature is created, it appears in every environment at once, normally in a safe, off state, and each environment can then decide independently what to do with it. This keeps the environments aligned in shape while leaving them free in decisions. It is a powerful defence against configuration drift.

When creating a feature, defaults can be applied

When a person creates a feature in Flagsmith, they can choose an initial enabled state and an initial value. By default these initial choices are applied to the new feature in all environments. That is convenient, but for a risky feature it may be exactly what you do not want, since production would also receive the starting value. Flagsmith offers project-level settings to prevent defaults from being applied to every environment, and many teams prefer to keep new features off everywhere except development. Check the project settings in your version to see the exact option and its name.

Comparing environments

Because the feature list is identical, comparing two environments is easy and meaningful. A useful habit is to review the difference between staging and production before a release. Flagsmith provides views that help compare environments, and teams can also fetch the settings of two environments through the management interface and compare them with a simple script. The question to ask is always the same: “Which features are in a different state here than there, and is each difference deliberate?”

How does an application tell Flagsmith which environment it belongs to? It shows a key. Understanding the two kinds of keys is one of the most important safety lessons in this guide.

The environment key

Every environment has an identifying key, a long string of letters and numbers. When your application starts, you give this key to the Flagsmith SDK. Each time the SDK asks for flags, it presents the key, usually in a request header, and Flagsmith uses it to find the right environment and to return that environment’s answers. In other words, the key is both the address and the proof of belonging. An application holding the staging key sees staging. It cannot see production, because it does not hold production’s key.

Two kinds of keys

The client-side key is designed so that exposing it is acceptable. A browser can see it in the page source, and that is fine, because it only allows reading the flags for a single user. The server-side key is more powerful. It can download the complete rules of the environment, and it must be stored like a password, in a secrets manager or in protected environment variables, and never placed into a web page, a mobile app, or a public code repository.

The API keys for management are different

Do not confuse environment keys with the keys used to manage Flagsmith itself. Environment keys are for applications reading flags. Management actions, such as creating a feature or changing a state through automation, use a different credential tied to a person or a service account, usually called an Admin API key or token. This second kind of key has far more power, because it can change flags, and it must be guarded even more carefully.

Rules for living with keys

• One key per environment per purpose. Never reuse the production key in a test setup.
• Keep server keys out of code. Read them from a protected setting at start-up.
• Rotate when in doubt. If a server key may have leaked, create a new one, switch your servers over, and delete the old one.
• Different keys for different services. If each back-end service has its own server key, a leak in one service is easier to contain.
• Never put secrets inside flag values. Flag values can be read by many systems. They are for behaviour, not for passwords.

How many environments should you create, and what should you call them? There is no single right answer, but there are sensible shapes that fit most teams.

Start from your delivery pipeline

The best guide to your environments is the path your code already walks on its way to customers. Each stage in the pipeline that needs different flag values deserves an environment. If your pipeline has a development stage, a staging stage, and production, then Flagsmith should have three environments with matching names. When the names match, nobody has to translate in their heads.

Common shapes

Naming rules that save headaches

• Use plain, predictable names. “Development,” “Staging,” and “Production” are understood by everyone.
• Match your infrastructure names. If your servers say “prod,” do not call the flag environment “live.”
• Keep production unmistakable. Many teams give production a distinctive colour in the Flagsmith interface so nobody edits it by accident. Flagsmith lets you choose a colour label for each environment.
• Write a description. A single line explaining who uses the environment and how it is deployed prevents long arguments later.

The cost of too many environments

It is tempting to create an environment for every possible purpose. But each environment needs care: its flags must be kept sensible, its keys managed, and its permissions reviewed. With ten environments and two hundred features, there are two thousand feature states to keep tidy. Environments that nobody uses become stale and misleading. A good rule is to create an environment only when you can name the person responsible for it and the situation in which it is used.

Creating an environment: what happens

A feature state is the heart of an environment. It is the actual answer to “what should happen here?” Let us look at what it can hold.

The parts of a feature state

For one feature in one environment, the feature state contains the following.

• Enabled or disabled. The main switch. A disabled feature returns “off” no matter what else is configured, unless the application chooses to look at the value.
• A value. Optional remote configuration, such as a number, a piece of text, or a small block of structured data. For example, “maximum upload size is fifty files.”
• Multivariate options. If the feature has several variants, each variant has a percentage of users in this environment. Development may give each variant an equal share, while production may give ninety percent to the old variant and ten percent to the new one.

An example across the pipeline

Consider a feature called “recommendation engine” that has a configurable value for how many items to show. A team might hold the following states.

Notice how a value can differ between environments for good reasons. A development environment may use a small test number, a staging environment a realistic one. Such differences are healthy, as long as they are known and intentional.

Same feature, different pace

Because states are separate, each environment can move at its own pace. Development changes freely, many times in a day. Staging changes when a release candidate is ready. Production changes only when the business is satisfied and the checks are green. In effect, the environments form a ladder: a change climbs one rung at a time, and each rung gives more evidence that it is safe.

flowchart LR
    D["Development: experiment freely"] -->|"Idea works"| S["Staging: rehearse as production will be"]
    S -->|"Tests pass and owners agree"| P["Production: gradual release"]
    P -->|"Problem"| R["Turn off in production only"]
    R --> D
    

The value of safe defaults

When code asks for a flag and Flagsmith cannot be reached, the code needs a fallback. Most SDKs let you supply a default value, which is used when the real answer is unavailable. Defaults are not stored in an environment. They live in your code. A good default is the old, proven behaviour, because it protects users when anything fails. Some SDKs can also be started with a copy of environment data saved earlier, so that even a first start during an outage has sensible answers.

Beyond the simple on and off switch, Flagsmith lets you give special answers to groups and to single users. The important point here is where these special rules live.

Segments: defined once, used separately

A segment is a named group of identities that match a set of rules. For example, “Beta testers” might mean identities whose trait group equals beta, or “Premium India” might mean identities whose plan is premium and whose country is India. Segment definitions belong to the project, so every environment understands the same segment names with the same meaning.

Segment overrides: the decision is per environment

A segment override says, “for this feature, in this environment, give people in this segment a special answer.” The override is stored inside the environment. That is a very useful feature. In staging, you might override the “new checkout” flag for the “QA testers” segment. In production, you might override it for the “Employees” segment first. The groups are the same everywhere, but the answers are chosen separately.

flowchart TB
    Q["Request: flags for identity 4821 in Production"] --> I{"Identity override exists?"}
    I -->|"Yes"| ANS1["Use the identity override"]
    I -->|"No"| SG{"Matches a segment override?"}
    SG -->|"Yes, highest priority wins"| ANS2["Use the segment override"]
    SG -->|"No"| ENVS["Use the environment default feature state"]
    ANS1 --> OUT["Return flag value to the application"]
    ANS2 --> OUT
    ENVS --> 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 the identity qualifies for, and when several segments match, a priority order decides which one wins. If none match, the plain environment value is used. This layered design means you can say “everyone gets this, except premium users, except this one person” in an orderly way.

Identities live inside an environment

When your application tells Flagsmith about a user, giving an identifier and some traits, that identity is recorded in the environment whose key was used. A person who exists in production does not exist in staging unless your staging application also reported them. This separation is healthy, because test users and real users never get mixed. It also means that traits used by segments must be sent by every environment’s application, or the segments will not match there.

Identity overrides: the personal touch

An identity override gives one specific identity a special answer for a feature in one environment. This is perfect for letting a single customer try a beta, or for helping a support engineer reproduce a problem. Identity overrides are also stored per environment, which means giving a person special access in staging says nothing about production.

Common ways teams use overrides in each environment

What actually happens when your application asks Flagsmith for flags? There are two main ways, and the choice affects speed, cost, and reliability.

Mode one: remote evaluation

In remote evaluation, the SDK sends a request over the internet each time it needs flags. It presents the environment key and, if relevant, the identity and its traits. Flagsmith’s servers run the rules and send back the answers for that user. This is simple, works with the client-side key, and is the normal mode for web pages and mobile apps. The cost is a network trip for each fetch, so applications usually fetch once at the start of a session and keep the answers in memory.

Mode two: local evaluation

In local evaluation, a server-side SDK uses the server-side key to download the whole environment’s rules, called the environment document, and keeps them in memory. From then on it computes the answers itself, with no network trip for each check. It refreshes the document in the background every so often. This makes flag checks extremely fast and keeps working if Flagsmith becomes briefly unreachable, because the last known rules are still in memory. The trade-off is that changes arrive after the next refresh, rather than instantly.

sequenceDiagram
    participant U as User
    participant A as Application
    participant SDK as Flagsmith SDK
    participant FS as Flagsmith API
    U->>A: Opens a page
    A->>SDK: Get flags for identity 4821
    SDK->>FS: Request with environment key and identity
    FS->>FS: Find the environment from the key
    FS->>FS: Apply identity overrides then segments then defaults
    FS-->>SDK: Flags and values for this identity
    SDK-->>A: Flag results kept in memory
    A-->>U: Shows the right version of the page
    

The role of the edge

Flagsmith offers an architecture designed to serve flag requests from servers spread across the world, so that answers are delivered quickly and reliably wherever your users are. In the hosted service, requests from SDKs are normally answered by this distributed layer rather than a single central database. For teams that run Flagsmith themselves, the deployment guide describes the options available, including the use of a local cache. The practical lesson is the same: whatever the internal machinery, applications should fetch flags sparingly, cache them, and always have a safe default.

Keeping the answers fresh in a browser or app

Browsers and phones cannot refresh as casually as servers. A typical approach is to fetch flags at the start of a session, store them, and refresh at moments such as returning to the app, or on a modest timer. Some SDKs also support receiving updates pushed from the server, so that a kill switch can act within seconds. Teams choose the balance between freshness and the load of constant polling according to how critical each flag is.

Offline and fallback behaviour

Good SDKs follow a ladder of fallbacks. First, use the answers already in memory. If the application restarts during an outage, use a saved copy of the last known environment data, when the SDK supports it. If even that is missing, use the default value written in the code. Designing every flag check with a safe default is one of the most valuable habits in the whole Flagsmith practice.

Since each environment keeps its own state, a change that works in development does not automatically appear in production. This is deliberate, and it means teams need a clear routine for carrying changes upward.

No automatic copying, by design

When you enable a feature in development, nothing happens in staging or production. That separation is the whole point. The cost is that someone must repeat the change in the next environment at the right moment. Flagsmith does not push states upward by itself, because pushing automatically would defeat the safety that separation creates. Instead, it gives you tools to make the manual step careful and visible.

The usual promotion routine

flowchart TB
    A["Create feature: OFF in all environments"] --> B["Enable in Development and build"]
    B --> C["Deploy code to all environments with flag OFF"]
    C --> D["Set Staging like next Production state"]
    D --> E{"Staging checks pass?"}
    E -->|"No"| B
    E -->|"Yes"| F["Request change for Production"]
    F --> G{"Approved?"}
    G -->|"No"| B
    G -->|"Yes"| H["Apply in Production gradually"]
    H --> I{"Healthy?"}
    I -->|"No"| J["Disable in Production"]
    I -->|"Yes"| K["Stable period then remove flag and old code"]
    J --> B
    

Tools Flagsmith provides for careful promotion

Why reviewed text beats hand clicking

When the shape of your environments is stored as text in a code repository, every change can be reviewed like code, recorded in history, and repeated exactly. A new environment can be created identically in minutes. Drift becomes easy to detect, because the written description and the real system can be compared automatically. Teams that run many environments, or many projects, gain the most from this approach.

Different environments deserve different levels of care. Flagsmith lets you give people exactly the access they need in each one.

The principle of least privilege

Least privilege means each person or system receives only the permissions necessary for their job, and nothing more. A developer may need to change anything in development, but only view production. A support engineer may need to manage identity overrides for customers in production, but should never change the value of a payment feature. A release manager may need to approve changes. Flagsmith lets administrators grant permissions at the organisation, project, and environment levels, and to individuals or to groups.

Typical permission levels at environment level

Teams and groups instead of individuals

Granting permissions person by person is slow and easy to forget. A better habit is to create groups such as “Developers,” “Release managers,” and “Support,” grant permissions to each group, and then place people into groups. When someone changes jobs, you update the group membership, and all their access changes at once. Many organisations connect Flagsmith to their company sign-in system, so that people use one account and are removed everywhere when they leave.

Approval flows for production

For the environments where mistakes cost the most, a second pair of eyes is a bargain. With change requests, a developer proposes “enable new checkout at ten percent,” and a colleague reviews the proposal. The reviewer checks that staging was rehearsed, that the right audience is selected, and that the timing is sensible. Only after approval does the change go live. The history is stored, so months later anyone can see who proposed it, who approved it, and why.

Notifications and visibility

Each environment can send webhooks, which are automatic messages to another system, whenever something changes. A common use is posting a line into a shared chat channel such as “Production: new checkout set to ten percent by Anil.” This simple habit means that when something odd happens, the first question, “what changed?”, is answered in seconds. Flagsmith also connects with analytics and monitoring tools through integrations that are configured per environment, so production data can go to production dashboards while development data goes elsewhere or nowhere.

Flagsmith environments become most useful when they line up with the stages of your delivery pipeline. Let us see how the two fit together.

A quick reminder about the pipeline

A delivery pipeline is an automatic assembly line that takes a code change from a developer’s laptop to production. It builds the code, tests it, stores the finished package, places it in a staging area, and finally releases it to customers. The same package moves forward through each stage. Nothing is rebuilt along the way. Only the settings change from stage to stage, and flag values are among those settings.

flowchart LR
    C["Commit"] --> B["Build and unit tests"]
    B --> DEV["Deploy to Development"]
    DEV --> T["Automatic integration tests"]
    T --> STG["Deploy to Staging"]
    STG --> UAT["Acceptance and performance checks"]
    UAT --> G{"Release approved?"}
    G -->|"Yes"| PRD["Deploy to Production"]
    PRD --> M["Monitor and roll out flags gradually"]
    DEV -.->|"uses Development key"| FD["Flagsmith Development environment"]
    STG -.->|"uses Staging key"| FS["Flagsmith Staging environment"]
    PRD -.->|"uses Production key"| FP["Flagsmith Production environment"]
    

How the pieces line up

The key is the only difference

The beauty of this design is its simplicity. The deployment step for each stage places the right environment key into the application’s settings. That is the entire difference between the stages as far as flags are concerned. The package, the code, and the SDK are identical. If staging behaves well, you have strong evidence about how production will behave, provided that staging’s flags truly resemble what production will have.

Separating deploy and release again

In an earlier lesson on continuous delivery, we learned that deploy and release are different events. Environments make this idea concrete. A deploy puts code onto production servers. A release changes the production flag state. The first is done by the pipeline, the second by a human or a rule, in the Flagsmith production environment. Because they are separate, deployments can happen many times a day, and releases happen when the business is ready.

Keeping environments aligned with releases

As a release approaches, a good habit is to make staging’s flags match the state that production will have on release day. Then the final tests in staging answer the real question: “Will production behave well after we change these flags?” If staging has flags that production will not have, the rehearsal proves nothing. Teams often add a step before each release to compare staging and production and explain every difference.

Environments help testing in several ways, but they also bring new questions. How do you keep tests repeatable when flags can change?

Repeatable tests need stable flags

An automatic test must give the same answer every time. If a test depends on a flag whose value people change during the day, the test becomes unpredictable. The cure is a dedicated environment for automatic tests, where flag values are fixed and changed only by the test team. Many teams create a “Test” environment for this reason. Another approach is for the test itself to set the flag values it needs, using the management interface, before it runs and to put them back afterwards.

Test both sides of every flag

Every flag has an off path and an on path. Automatic tests should cover both. A very common failure is testing only the new path, while the old path quietly breaks, so that turning the flag off in an emergency leads to a worse failure. Use the test environment, or local overrides, to run the same suite with each important flag on and off.

Temporary environments for isolation

Larger teams sometimes create a temporary environment for each pull request or each feature branch. The pipeline creates the environment through the Admin API, runs the tests against it, and deletes it afterward. This isolation means two developers can test conflicting flag settings at the same moment without interfering. The price is the automation effort and the need to clean up reliably, since forgotten temporary environments pile up.

Testing safely in production

No staging environment is exactly like production. Real traffic, real data, and real integrations behave in ways rehearsals cannot copy. Flagsmith makes careful testing in production possible. A segment override can switch a new feature on for employees only, or for a short list of identities, while everyone else sees the old behaviour. The team can use the feature on real systems, find the problems staging missed, and fix them before customers ever see them.

The combinations problem

If a program has ten flags, there are over a thousand ways they can be combined. No team can test every combination. The skill lies in testing the ones that matter: the planned production state, the planned next state, the old state used as a fallback, and any pairs of flags that touch the same screen or data. Environments help because each one can hold a different important combination at the same time.

Environments are a powerful idea, and like any powerful idea they bring both gains and costs. A sensible engineer weighs both.

Key trade-offs to decide on purpose

One project or several?

A frequent question is whether to put several applications into one Flagsmith project or to give each its own. Because features and segments are shared across the environments of a project, the project should hold things that belong together. A mobile app and its back end that evolve together may share a project, so a single feature can be read by both. Two unrelated products should have separate projects, otherwise their feature lists become a confusing mix and permissions become hard to express.

A flag dashboard is a remote control for your product. Environments are the first and strongest line of defence for that remote control.

Isolation is the main security feature

The biggest security gain from environments is isolation. An application with the development key cannot read or change production. A mistake, a leak, or a malicious act in a lower environment stays in that lower environment. This is why you must never reuse a production key outside production, even “just for a quick test.”

Protect the server-side key and the admin key

As we learned, the client-side key is public by design, while the server-side key and any administrative token must be secret. Store them in a proper secrets manager, grant access only to the services that need them, and rotate them on a schedule and after any suspected leak. Never commit them to a code repository, even a private one, since repositories are copied and shared more widely than people expect.

Privacy of user data

Identities and traits can contain personal information. Good practice is to send only what the rules truly need. Use opaque identifiers rather than names or email addresses, and send traits such as “plan” or “country” instead of anything sensitive. If your Flagsmith runs 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 also helps, since identity details can stay inside your own servers while only the rules are downloaded.

Separate test data from real data

Because identities live inside the environment whose key reported them, test users and real users never mix. Keep it that way. Never load real customer data into development or staging identities, since lower environments are usually protected less strictly. Use made-up test identities and traits instead.

Audit, access reviews, and compliance

• Audit log. Keep the history of changes. Many compliance rules require proof of who approved production changes.
• Regular access reviews. Every few months, check who holds permissions in production and remove anyone who no longer needs them.
• Single sign-on. Connect Flagsmith to the company identity system so people leave access when they leave the company.
• Separation of duties. The person who proposes a production change should not be the only one who approves it.
• Break-glass access. Define a documented emergency path for turning a feature off quickly, with extra review afterward.

Self-hosting and data location

Teams with strict rules about where data may live sometimes choose to run Flagsmith on their own infrastructure, in a region of their choice, behind their own network controls. In that case, the same environment design applies, but the responsibility for updates, backups, and availability moves to the team. It is a serious decision, and the rewards of control must be weighed against the work of operating the service reliably.

When flags change what users see, you need to know whether the change helped or harmed. Observability is how you find out.

Know which environment you are looking at

The first rule of monitoring in a multi-environment world is that every graph, log line, and alert must be labelled with the environment it comes from. A spike of errors in development is normal. The same spike in production is an incident. If the labels are missing, people waste time and make wrong decisions. Tag your metrics with the environment name, and keep separate dashboards, or clear filters, for each.

Tag signals with flag states

The most useful habit is to record which flag variation a request ran with. Then any graph can be split into two lines: users with the feature and users without it. The question “is the new checkout slower?” becomes a comparison of two lines. Flagsmith can send flag evaluation data to analytics and monitoring tools through integrations, and many teams also add the flag state to their own logs.

Guardrail metrics during a production rollout

Before raising a production flag, a team writes down the numbers that must not get worse: error rate, slow-request time, payment success, app crashes, and support contacts. These are called guardrail metrics. If any one crosses its limit, the rollout pauses or reverses. Because the change is a flag in a single environment, reversing it is a matter of one click in production, with no redeployment.

flowchart TB
    A["Change flag state in Production"] --> B["Webhook posts note to team channel"]
    A --> C["Audit log records who, what, when"]
    A --> D["Applications receive new state"]
    D --> E["Metrics tagged with environment and flag state"]
    E --> F{"Guardrails healthy?"}
    F -->|"Yes"| G["Continue to next step"]
    F -->|"No"| H["Alarm and flag disabled"]
    H --> I["Investigate with logs and traces"]
    

Watch the health of the flag setup itself

Besides watching features, watch the plumbing. How often do SDKs fail to reach Flagsmith? How old is the rule data held in each server? How many requests 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.

Cost and volume

A busy service may check flags for every request. Sending an event for each check would produce enormous volumes. Teams control this with sampling, by sending summaries instead of single events, and by sending detailed data only for flags used in experiments. Keep in mind the usage limits of your Flagsmith plan, since the number of requests per month may be part of the pricing model.

A flag check can happen on almost every request, so speed and dependability matter. Environments add their own questions about scale and failure.

Keep flag checks cheap

If every flag check required a trip across the internet, a page with twenty flags 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 that 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

Everything fails sometimes, so the design assumes it. These protections are the main ones.

Eventual consistency between servers

When a flag is changed, 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 may have the old state and some the new. For most features this is harmless. For multi-step journeys such as a checkout, make the decision once at the start, store it with the session, and reuse it, so that a user never sees the design change halfway through.

Scaling to many environments and many flags

The size of an environment’s data grows with the number of features, segments, and overrides. A very large environment document means a bigger download for local evaluation and more memory on every server. Tidy habits keep it light: delete finished flags, remove unused segments, and avoid creating thousands of identity overrides when a single segment rule would do.

Mobile apps and slow updates

Once an app version is installed, its code cannot change until the person updates. Flags therefore act as a remote control for features already inside the installed app. Because the environment key inside a released app points to production, you can switch a faulty feature off on millions of phones without waiting for an app store review. Take care that flags guarding code absent from older app versions include a condition on the app version, so that old apps do not wait for a feature that was never built into them.

A pattern is a proven solution to a repeating problem. An anti-pattern is a tempting solution that causes trouble. Learn both.

Patterns worth adopting

Anti-patterns to avoid

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

Best practices

• Match environments to pipeline stages. Use the same names in the pipeline and in Flagsmith so nobody has to translate.
• Start with three environments. Development, Staging, and Production cover most needs. Add more only with a clear owner and purpose.
• Make production unmistakable. Give it a distinctive colour and a clear description so nobody edits it by accident.
• Create features switched off. Enable them deliberately, starting in development.
• Use the client-side key in client code and the server-side key only on servers. Keep server keys in a secrets manager.
• Give each service its own key. A leak is then easier to find and contain.
• Apply least privilege. Be generous in development and strict in production, using groups instead of individuals.
• Use change requests for critical features in production. A second pair of eyes is cheap protection.
• Mirror staging to the next production state before each release. Make the rehearsal predict the performance.
• Compare environments regularly. Explain every difference or fix it.
• Always supply safe defaults in code. The default should be the old, proven behaviour.
• Label every metric and log with the environment name. Avoid confusing a development spike with a production incident.
• Announce production changes in a shared channel. Use a webhook so that everyone sees what changed.
• Delete finished flags and unused environments. Cleaning is part of the job, not an optional extra.
• Describe your setup as code when it grows. Repeatable beats hand-clicked.

Common mistakes

Adopting environments in a team that already uses flags

Many teams meet environments after they already have a pile of flags in a single place. Moving to a clean structure is possible without stopping work, if it is done in small, careful steps.

It also helps to talk openly about culture. Environments work best in teams where turning something off in production is treated 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 main strength of flags, their speed, is wasted. Teams that celebrate a quick, calm reversal and study it without blame become safer over time. Write down the simple rules, such as which environment is used for what and who may change production, and put them where every new joiner will see them on the first day.

A short checklist before changing a production flag

The idea of separate stages with separate settings is common to the best-known engineering organisations. Here are public lessons you can use, followed by an illustrative story built on Flagsmith.

An illustrative story: a media app launching a new player

The following story is an invented example, shown to tie the ideas together. A video streaming company has a project in Flagsmith with three environments: Development, Staging, and Production. A feature called “new video player” is created, switched off everywhere.

Patterns in all these stories

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

You have travelled from the danger of a single shared switchboard to a well-organised set of separate, safe stages. Here is what to remember.

A Flagsmith environment is a separate, self-contained set of decisions about your features, together with its own keys, overrides, permissions, and history. The project defines what exists, and each environment decides what is true here. With environments, developers can experiment boldly, testers can rehearse realistically, and production can be protected carefully, all while one build of the code moves unchanged through every stage. The practical habit to carry away is simple: before touching any flag, ask which environment you are standing in, what it is for, and who will feel the change. Teams that make this question automatic rarely suffer the painful Friday surprises that first led them to adopt environments, and they ship new features with calm confidence, because each stage has already proven what the next one needs to know.