Before moving anything anywhere, it helps to understand what is being moved and why there are several places to move it between.

What is a software environment?

A software environment is a separate copy of your running system, set up for a specific purpose. Your Development environment is where engineers try things and break things. Your Staging environment is a close rehearsal of the real system, used for testing before release. Your Production environment is the real thing, the one customers actually use. Each has its own servers, its own data and, importantly for this guide, its own configuration.

Why keep them apart? Because mistakes are cheap in Development and expensive in Production. A bug that makes a test page crash is a small lesson. The same bug on a live shopping site during a sale is a headline. Environments give you a place to be wrong without anyone outside the team noticing.

What is a feature flag?

A feature flag, also called a feature toggle or feature switch, is a condition in your application that decides whether a piece of behaviour is active. The code for a new feature is shipped to every environment, but it stays hidden behind the flag. When the flag is off, users see the old behaviour. When the flag is on, they see the new one. The decision is stored outside your code, so changing it does not need a new deployment.

This idea separates two things that used to be glued together: deploying code and releasing a feature. Deploying means putting new code on servers. Releasing means letting users experience it. With flags, you can deploy on Tuesday and release on Friday, or release to ten percent of users first, or switch the feature off in seconds if something looks wrong.

What is Flagsmith?

Flagsmith is a service that stores your flags and hands their current state to your applications. You can use the hosted version or run it yourself, because the core is open source. Your application asks Flagsmith a simple question, such as “is the new checkout enabled for this user right now?” and receives an answer. Beyond simple on and off switches, Flagsmith also stores remote configuration values, such as a text message, a number or a small block of settings, and it can give different answers to different groups of users.

All of the answers are organised by environment. The same flag can be off in Production, on in Staging and set to a different value in Development. That freedom is the whole point, and it is also why promotion needs care.

What does promoting a flag mean?

Promoting a flag means taking the decision you made in one environment and applying the same decision in another, usually the next one up the ladder. You tested the new checkout in Staging with the flag on for the internal team. Now you want the equivalent setup in Production, perhaps starting with a small slice of real customers. Promotion is the careful transfer of that intent.

Eight words explain almost everything in the dashboard. Learn them once and the rest of this guide reads easily.

Flagsmith organises everything in a simple hierarchy. At the top sits your organisation, which represents your company or team and holds users, billing and permissions. Inside an organisation you create projects, one for each application or product you manage. Inside a project you have environments, and inside each environment you find the state of every feature.

flowchart TD
    ORG["Organisation"] --> P1["Project: Web Shop"]
    ORG --> P2["Project: Mobile App"]
    P1 --> F["Features and Segments defined once per project"]
    P1 --> E1["Environment: Development"]
    P1 --> E2["Environment: Staging"]
    P1 --> E3["Environment: Production"]
    E1 --> S1["Feature states and overrides for Development"]
    E2 --> S2["Feature states and overrides for Staging"]
    E3 --> S3["Feature states and overrides for Production"]
    F -.-> S1
    F -.-> S2
    F -.-> S3

Read the diagram from top to bottom. The organisation holds projects. A project holds one shared list of features and segments, shown in the box on the left. The same project also holds several environments. The dotted lines show that every environment looks at the shared list, but each environment keeps its own private state for every item on that list. This split between “defined once” and “configured many times” is the single most important idea for understanding promotion.

Client-side and server-side keys

Each environment has a client-side environment key and a server-side key. The client-side key is meant for apps that run on a user’s device, such as a web page or phone app. It is considered public and can only read flags. The server-side key is meant for your backend services. It is secret, and it unlocks extra abilities such as local evaluation, where your own server downloads the rules and decides flags without calling Flagsmith each time.

Because these keys belong to one environment, a Staging app can never accidentally read Production flags, and the reverse is also true. That protection is also why nothing moves between environments on its own. Your Staging app asks Staging questions and receives Staging answers.

“Copy the flag to Production” sounds like one action. In reality it is several separate pieces, and you should decide on each one deliberately.

Two layers: the definition and the state

Every flag has a definition and a state. The definition is the flag’s identity: its name, its description, its tags and its type. It is created once, at the project level. The state is how the flag behaves right now in one specific environment: whether it is enabled, what value it carries, which segments get special treatment, and which individual users get their own override.

Because the definition is shared, a newly created flag appears in every environment of the project right away, typically switched off. You do not need to “create it again” in Production. What you do need to do is set its state there. That is the real meaning of promotion.

flowchart LR
    DEF["Flag definition: name, description, tags"]
    DEF --> ST["Environment state"]
    ST --> EN["Enabled or disabled"]
    ST --> VAL["Remote value"]
    ST --> MV["Multivariate split percentages"]
    ST --> SEG["Segment overrides in priority order"]
    ST --> ID["Identity overrides"]
    SRC["Source environment"] -. "decision to copy" .-> ST

The figure shows the definition on the left and the five pieces of environment state on the right. The dotted arrow at the bottom is promotion: you take decisions made in a source environment and apply them to some or all of those five pieces in the target. Let us look at each piece in plain words.

Which pieces should you usually copy?

There is no universal answer, but there is a sensible default. Enabled position, segment overrides and multivariate percentages usually describe a release plan, so they are good candidates for promotion. Remote values often contain environment-specific details such as web addresses, account numbers or limits, so copy them only after reading them. Identity overrides almost always belong to people who exist in one environment only, since the user “tester-42” in Staging is not a real customer in Production. Treat them as not promoted unless you have a specific reason.

Promotion always travels along a path. Knowing the shape of that path tells you how careful each step should be.

Most teams arrange their environments as a ladder with the safest, noisiest rung at the bottom and the most protected rung at the top. A flag climbs one rung at a time, and at each rung it must prove itself before moving up. The number of rungs varies by company. A small start-up may have only Development and Production. A large bank may have six or seven stages, including security testing and a regulatory sign-off stage.

Notice how the column “Who should edit flags” narrows as you climb. This is deliberate. In Development, speed matters most, so everyone can change anything. In Production, accuracy matters most, so changes should be rare, visible and reviewed. Flagsmith supports this with roles, permissions and, on paid plans, formal change approval, which later chapters describe.

Why not just use one environment with a different flag name?

Some beginners try to avoid environments by creating flags named “checkout_test” and “checkout_live”. This quickly turns into chaos. Names drift, people flip the wrong one, and the code needs to know which name to read in which place. Real environments solve this cleanly: the code reads one flag name everywhere, and the environment key decides which set of answers comes back.

There is more than one good way to carry a flag’s settings upward. The right choice depends on how many flags move, how often, and how much control your organisation needs.

Flagsmith is a flexible tool, and what you see in the dashboard depends on your edition and version. Some helpers, such as approval workflows and scheduling, are part of paid plans. Others, such as the programmable Admin API, are available widely. The table below lists the methods you will meet in this guide, with an honest view of when each one fits.

The simplest method is also the one every team should understand first, because every other method is a faster or safer version of the same moves.

Manual promotion means you open the flag in the source environment, read what it says, open the same flag in the target environment, and make it match. It needs no special tools and no extra permissions beyond the right to edit flags in the target. For a handful of flags, it is perfectly reasonable. The danger is not the method itself but the lack of a written routine, so here is a routine you can follow every time.

Why “start disabled” matters

A flag is read the moment you save it. If you flip the main switch on first and then spend two minutes adding segment rules, then for those two minutes every user can see the feature. Building the safe configuration first and switching on last avoids that window. It is the same habit as plugging in an appliance only after it is assembled.

Where manual promotion breaks down

The method works until the number of flags grows. Copying three flags is an easy afternoon. Copying forty is an invitation for typing errors, forgotten segments and tired eyes. Manual work also leaves no machine-readable record of intent, so two people may follow slightly different routines. When you notice yourself saying “I’ll just do it quickly” about a Production change, that is the signal to move to a more structured method from the next chapters.

Before you change anything, it helps to see exactly how two environments differ. That view turns promotion from a guess into a checklist.

What is configuration drift?

Configuration drift is the slow, unplanned difference that grows between environments over time. Someone turns a flag on in Staging for a demo and forgets it. Someone edits a value in Production during an incident and never copies the change back. After a few months, nobody can say with confidence what Staging proves about Production. Drift is dangerous because it quietly weakens the main reason you have Staging at all.

How comparison helps

Flagsmith provides comparison tooling in the dashboard that lets you place two environments side by side and see which features differ in their enabled position or value. Depending on your version, you may also see differences in segment overrides. Treat this screen as a map. Green areas, where both sides agree, need no work. Highlighted rows show the places where promotion would change something.

Sometimes you do not need to move one flag. You need an entire new environment that starts life looking like an existing one.

What is cloning?

Cloning means creating a new environment and asking Flagsmith to copy the contents of an existing environment into it. The new environment gets its own fresh keys, but it begins with the same feature states and segment overrides as the original. You then adjust whatever needs to differ. Check your version’s documentation for exactly which items are copied, because identity overrides in particular may or may not be included.

When cloning is the right tool

Things to fix straight after cloning

For Production, many organisations want a second pair of eyes and a clear record. Flagsmith offers a workflow for exactly that on its paid plans.

What is a change request?

A change request is a proposal to change a flag in an environment. Instead of saving the new state immediately, the editor submits it. A colleague with the right permission reviews the difference, then approves or rejects it. Only after approval does the change go live. The idea comes from code review, where nobody merges their own work unseen, applied to configuration instead of code.

sequenceDiagram
    participant RO as Release Owner
    participant FS as Flagsmith
    participant RV as Reviewer
    participant APP as Production App
    RO->>FS: Propose new flag state for Production
    FS->>RV: Notify that a change is waiting
    RV->>FS: Inspect the difference and approve
    FS->>FS: Apply now or wait for scheduled time
    APP->>FS: Ask for current flags
    FS-->>APP: Return updated state

Follow the arrows from top to bottom. The release owner proposes a new state, and Flagsmith holds it without applying it. A reviewer is notified, looks at exactly what would change and approves it. At that point Flagsmith applies the change immediately, or waits until a scheduled time you chose. From then on, whenever the live application asks for flags, it receives the new state. The production app never sees a half-reviewed change.

Scheduling

Scheduling lets you attach a date and time to an approved change. This is valuable for launches that must happen at a precise moment, such as the opening of a sale at midnight, when you would rather not have a person awake and nervous. It also helps global teams: the approval can happen during working hours while the switch happens at a quiet time for customers.

When flags number in the dozens or hundreds, human clicking stops being the safest path. Automation makes promotion boring, and boring is the best quality a release step can have.

What is an API?

An API, short for application programming interface, is a doorway that lets one program talk to another with agreed rules. Flagsmith has an Admin API, a set of doors designed for management tasks rather than for end-user flag lookups. Anything you can do by clicking in the dashboard, such as reading a flag’s state in one environment or changing it in another, can in principle be done by a script calling this API. You need a secure token that proves the script is allowed to do so.

What is infrastructure as code, and where does Terraform fit?

Infrastructure as code means describing your systems in text files that are stored, reviewed and versioned like software. Terraform is a widely used tool for this. A Terraform provider exists for Flagsmith, which means you can describe projects, environments and feature states in files, then let Terraform make reality match the description. Check the current provider documentation to see which resources it supports in your version.

flowchart LR
    A["Engineer proposes flag change in a file"] --> B["Peer review of the change"]
    B --> C["Automated checks run"]
    C --> D["Apply to Staging environment"]
    D --> E["Verification tests pass"]
    E --> F["Apply to Production through approval gate"]
    F --> G["Audit log and webhook alert the team"]

The pipeline in the figure starts with a text change proposed by an engineer. A colleague reviews it exactly as they would review code. Automated checks then look for obvious mistakes, such as a flag named in the wrong style. The change is first applied to Staging, where tests confirm the behaviour. Only then is it applied to Production, and even there it passes through an approval gate. The final step records the change and alerts the team, so nobody is surprised.

Why automation improves safety

Designing a promotion script wisely

Targeting rules are where promotion gets subtle. The same rule can mean very different things in two environments, because the people inside them are different.

Segments: defined once, applied separately

A segment is a saved description of a group of users, built from rules about their traits. For example, “plan equals premium and country equals India” is a segment. Segments are defined at the project level, so the same definition is available in every environment. That is helpful, because the rule means the same thing everywhere. What differs is which flags use the segment in which environment, and what each override says.

Imagine a segment called “Internal Staff”. In Staging it might give early access to the new checkout to every employee. In Production you may want the same segment to see the feature first, as a safe first audience. Here the segment and the intent carry over neatly. But consider a segment called “Beta Testers”. In Staging it may include dozens of synthetic test users. In Production it might include only a handful of volunteers. The rule is identical, but the audience size and risk are not.

Segment override priority

A flag can have several segment overrides, and a single user can belong to more than one segment. Flagsmith decides which override wins by looking at the order of the list, with the top entry taking priority. This is similar to a set of rules at a building entrance: the guard checks the first rule, and if it applies, stops there. If you rebuild the list in a different order in the target environment, users in two overlapping segments may suddenly see different behaviour.

Identity overrides

An identity override gives one specific user a special answer regardless of other rules. It is the sharpest tool in the box, useful for letting a support agent preview a feature on a real account, or for excluding a troublesome customer. Because identities are usually unique to each environment, identity overrides rarely make sense to promote. The identifier “user-8841” in Staging might not exist in Production, or worse, might belong to a different real person.

Not every flag is a simple switch. Some choose between several options, and some reveal a feature to only a slice of users. Both need special attention during promotion.

What is a multivariate flag?

A multivariate flag has more than two possible results, called variants. A button might be blue, green or orange. A recommendation engine might use algorithm A or algorithm B. Each variant gets a percentage, and together they add up to one hundred. Flagsmith assigns each user to a variant using a stable calculation based on their identity, so the same user keeps seeing the same variant visit after visit. That stability matters, because a button that changes colour on every page load would ruin both the experience and the experiment.

What is a percentage rollout?

A percentage rollout is a segment-style rule that includes a fixed share of users, such as five percent. Because the assignment is stable, the five percent who see the feature today are a subset of the twenty-five percent who see it next week. People do not flicker in and out as you widen the audience, which is exactly what you want.

How to promote percentages sensibly

When you copy a multivariate allocation from Staging to Production, resist the urge to copy the final numbers straight over. In Staging, a flag at one hundred percent is normal, because your testers need to see it. In Production the same flag should start at the smallest sensible percentage and climb in steps. The promotion is the same flag with a different, more cautious starting point.

Everything so far comes together here: one repeatable path a team can follow from first idea to retired flag.

flowchart TD
    A["Create flag in project"] --> B["Configure in Development and test"]
    B --> C{"Works as planned?"}
    C -- "No" --> B
    C -- "Yes" --> D["Deploy code to Staging"]
    D --> E["Promote settings to Staging"]
    E --> F{"QA and checks pass?"}
    F -- "No" --> B
    F -- "Yes" --> G["Deploy code to Production with flag off"]
    G --> H["Compare Staging and Production"]
    H --> I["Submit change request for Production"]
    I --> J["Approved and applied to small audience"]
    J --> K{"Metrics healthy?"}
    K -- "No" --> L["Switch off and investigate"]
    K -- "Yes" --> M["Widen audience in steps"]
    M --> N["Reach everyone"]
    N --> O["Remove the flag and old code"]

Trace the figure from the top. The flag is created once in the project and configured in Development. Two diamond-shaped questions follow: does it work as planned, and do the checks in Staging pass? A “no” in either place sends the work back to the beginning, which is cheap. After Staging, the code is deployed to Production with the flag still off, so the new code path exists but nobody can reach it. A comparison and a change request then introduce the flag to a small audience. A third question asks whether the metrics look healthy. If they do not, the flag goes off immediately. If they do, the audience widens in steps until everyone has the feature, and finally the flag and its old code are removed.

The deployment-before-release rule

Notice that the code reaches Production before the flag is switched on there. This ordering matters. It means deployment risk, such as a build problem or a missing database change, is separated from release risk, such as a confusing screen. If something breaks after deployment with the flag off, you know the cause is the deployment. If it breaks after the flag goes on, the cause is the feature. Separating the two makes diagnosis fast.

The pre-promotion checklist

A flag in Production can change what real customers see in seconds. That power deserves the same protection as a deployment key.

Roles and permissions

Flagsmith lets you control who can do what, at the organisation, project and environment levels. A sensible setup lets many people view flags, a smaller group edit them in lower environments, and only a few named people change Production. On plans that support it, you can also set permissions per environment so that a developer who edits Development freely has read-only access to Production. This is the principle of least privilege: each person gets only the power their job needs.

Protecting keys and tokens

Two kinds of secrets matter. The server-side environment key lets backend services read flags and, in local evaluation mode, the full rule set. The Admin API token allows management actions. Store both in a secrets manager, never in source code. Give each environment its own pipeline credentials, so a leak in Staging cannot become a Production incident. Rotate them on a schedule and immediately after any suspected exposure.

The audit log

An audit log is a diary kept by the system that records who changed what and when. Flagsmith keeps one for flag changes, so you can answer the questions that always come after a surprise: who turned this on, at what time, from which state to which state. It is the first place to look when a comparison between two environments reveals something nobody expected.

Saving a flag in the dashboard is not the same as every user seeing it. Understanding the delay, and watching for trouble, completes the promotion.

Why changes are not instant

Between the dashboard and a user’s screen sit several layers that store recent answers to avoid asking the same question again and again. Your application may keep flags in its own memory for a short time. Client SDKs may cache results on the device. Server SDKs in local evaluation mode download the rule set and refresh it on a timer, often around once a minute by default. Any content delivery network or proxy in front of Flagsmith may hold answers briefly too. The sum of these delays is the time from saving a change to the last user seeing it.

Planning around the delay

What to monitor after promotion

Monitoring means watching measurements that tell you whether a system is healthy. After a flag changes in Production, the most useful measurements are the ones tied to the feature: error rates, response times, successful completions of the journey the flag affects, and any rise in support contacts. Compare the group seeing the new feature against the group not seeing it, because overall averages hide small groups.

Theory is easier to trust when you watch it work. Here is one made-up team taking one flag all the way to customers.

Meet BrightCart, an imaginary online shop. Its developers have built a redesigned checkout page and wrapped it in a flag called new-checkout. The flag has a simple on and off position, plus a remote value called payment_mode that tells the page whether to talk to a practice payment system or the real one. BrightCart’s Flagsmith project has three environments: Development, Staging and Production.

What would have gone wrong without the routine?

Suppose the team had skipped the comparison and simply cloned the Staging settings. The flag would have gone on for every customer immediately, and payment_mode would have stayed on practice. Customers would have completed checkouts that looked successful but never charged a card, and the shop would have shipped free goods until someone noticed. The routine described above is not bureaucracy. It is the shortest path around that kind of story.

Separate environments with careful promotion bring clear benefits and real costs. Knowing both helps you choose the right amount of process.

Choosing how much process you need

There is no single right amount of ceremony. A three-person start-up with ten flags can happily promote by hand with a shared checklist. A company with hundreds of engineers and strict audit duties needs approvals, automation and permissions. The danger lies at both ends: too little process creates incidents, and too much process teaches people to bypass the system. A useful rule of thumb is to add structure only where a mistake would be costly, and to leave lower environments light and fast.

Flags come in a few well-known shapes. Recognising the shape tells you how long the flag should live and how carefully it should be promoted.

Anti-patterns to avoid

An anti-pattern is a common habit that looks reasonable but causes harm over time. Each box below describes one, explains the damage and suggests a better route.

A short collection of habits that experienced teams share, followed by a guide for the moment when a promotion does not behave as expected.

Habits worth building

If a promotion does not behave as expected

Promotion is much easier when the layout underneath it is sensible. A few decisions made early can save months of confusion later.

One project or many?

The first decision is how to divide your work into projects. A project in Flagsmith is a shared pool of flags and segments, so everything inside it can see the same names and the same audience rules. If one product is built by several teams who all need the same segments, such as “paying customers” or “internal staff”, a single project keeps those definitions in one place. If your company runs several quite separate products, each with its own users and its own release rhythm, separate projects stop their flags from cluttering each other’s lists.

A useful question to ask is: would these two systems ever want to share a segment or a flag? If the answer is yes, they probably belong together. If the answer is no, and mixing them would only make the flag list longer and more confusing, give each its own project. Companies with many autonomous teams, such as the squad model Spotify has publicly described, often lean towards one project per product area so each team can move at its own speed without tripping over the others.

How many environments?

Start with as few as your risk allows. Two environments, one for building and one for customers, is a respectable beginning. Add a Staging environment when you find that changes behave differently on real infrastructure than on laptops. Add further stages only when a specific group needs its own space, such as a dedicated test environment for a partner integration or a regulated sign-off stage. Every extra environment is another place for settings to drift, so each one should earn its keep.

Naming that survives growth

Names are the cheapest form of documentation. Agree on a style for environments, projects, segments and flags before you have fifty of each. Environment names should say what they are for, such as Development, Staging and Production, not whose they are or when they were made. Segment names should describe the group in business words, such as “internal-staff” or “trial-customers”, not the rule used to build it, because rules change and names stick. Flag names should describe the behaviour being controlled, written the same way every time.

Regional and customer-specific environments

Some businesses need environments for different regions, for different legal regimes or for large customers with special arrangements. These are sometimes necessary, but they multiply the promotion work, because each regional Production now needs the same careful steps. Before creating them, ask whether a segment based on region or customer would do the same job inside a single Production environment. Segments are lighter, easier to promote and easier to remove. Create separate environments only when the data, the keys or the legal boundaries truly have to be separate.

A flag creates two versions of your application in one build. Both must work, and so must the act of switching between them.

Two doors, two tests

Every flag turns a single path through your code into a fork. When the flag is off, users take the old path. When it is on, they take the new one. A common and costly mistake is to test only the new path, because it is the exciting one. The old path matters just as much, since it is the one customers rely on until the release is complete and the one they fall back to if you switch the flag off during trouble.

Layers of testing

The explosion of combinations

One flag gives two paths. Two flags give four. Ten flags give over a thousand combinations. Nobody tests every combination, and nobody should try. Instead, keep flags independent wherever possible, test each in isolation, and test explicitly the few combinations that are likely to meet in Production. This is one more reason to remove old flags quickly: every retired flag cuts the number of possible worlds in half.

Testing the promotion, not only the feature

The feature may work perfectly and the promotion may still be wrong. A segment may have been given the wrong priority. A value may have been copied that should have differed. The wrong audience percentage may have been typed. To catch these, create a small set of test identities that represent each audience, such as a staff member, a trial customer and a regular customer, and check what each one receives in the target environment after every promotion. Doing this takes minutes and catches an entire class of errors that feature tests never see.

One of the greatest gifts of feature flags is the ability to undo a release in moments. That gift is only useful if the team has practised unwrapping it.

What is a rollback?

A rollback means returning a system to a previous, known-good state after a change causes trouble. In traditional releases, this meant deploying the old code again, which could take many minutes or hours. With a flag, the old behaviour is still sitting in the code, so rolling back is a matter of switching the flag. The result reaches users within the refresh period of your SDKs, which is usually seconds to a minute or so, as discussed earlier.

Rollback or roll forward?

Sometimes the best answer is not to undo the change but to fix it quickly and continue. This is called rolling forward. A small, obvious defect with a certain, tested fix may be faster to patch than to withdraw. But when the cause is unclear, customers are affected and the stakes are high, switching the flag off is almost always the safer first move. It buys time. Investigation can then happen calmly, without customers paying for every minute of thought.

flowchart TD
    A["Alert: error rate or complaints rising"] --> B{"Started after a flag change?"}
    B -- "Yes" --> C["Switch the flag off or reduce its audience"]
    B -- "No" --> D["Use the normal incident process"]
    C --> E["Wait one refresh period"]
    E --> F{"Metrics recovering?"}
    F -- "Yes" --> G["Record cause and plan the fix"]
    F -- "No" --> D
    G --> H["Repeat the change in lower environments"]
    H --> I["Review and update the runbook"]

Read the figure from the alert at the top. The first question is whether the trouble began just after a flag change. The audit log answers this in seconds. If yes, the fastest safe move is to switch the flag off or shrink its audience. After waiting for one refresh period, check whether the measurements recover. If they do, the team records the cause and plans a proper fix. If they do not, the flag was not the culprit, and the team continues with the ordinary incident process. At the end, the change is reproduced in lower environments and the runbook is improved so the next incident is easier.

What a good runbook contains

Flags are cheap to create and easy to forget. Without a lifecycle, they pile up like unopened mail, and every pile hides a few things that matter.

What is flag debt?

Flag debt is the accumulated cost of flags that have outlived their purpose. Each one keeps an unused code path alive, adds a decision to every future change and invites someone to flip it by accident. A project with two hundred flags, of which only thirty are still doing real work, is slower to understand, slower to test and riskier to change. Like financial debt, a little is normal, and a lot becomes crippling.

The lifecycle of a typical flag

Governance in plain words

Governance simply means agreed rules about who may do what, and how the group checks that the rules are followed. For flags, the useful rules are few. Every flag has an owner. Every flag has a purpose and an expected lifetime. Production changes are made by named people or through approval. Stale flags are reviewed on a regular schedule, perhaps monthly or at the end of each release cycle. A short review meeting with the list of long-lived and stale flags is often enough to keep the project healthy.

At small scale, nobody asks how flags are delivered. At large scale, it is one of the first questions, because every request may need an answer.

How applications get their flags

There are two broad ways for an application to learn a flag’s value. In the first, the application asks Flagsmith each time it needs an answer, or at the start of each user session, and Flagsmith replies. In the second, a backend service downloads the whole set of rules for its environment from time to time and evaluates flags locally, in its own memory. The first is simple and always fresh. The second is extremely fast and keeps working even if the network to Flagsmith is briefly interrupted, at the cost of a short delay before changes arrive.

Habits that keep flags fast

Thinking about millions of requests

Suppose your shop serves one thousand requests every second, and each request needs the value of three flags. If every request called out to a flag service, that would be three thousand extra calls every second, each adding delay. With local evaluation or good caching, the same traffic causes a small, steady trickle of refreshes, measured in a handful of calls per minute per server. The design choice is the difference between a flag system that disappears into the background and one that becomes a bottleneck during your busiest sale.

Large companies that serve enormous traffic, such as Netflix, have described building systems where configuration is pushed or cached close to where it is used so no single central service is asked each time. Flagsmith’s approach to local evaluation and its edge delivery options are meant for the same style of design, though the exact choices available depend on your edition, so confirm them in the current documentation.

Promotion and performance together

Promotion affects performance in an indirect way. When you widen a flag’s audience, you also widen the load on the new code path. A feature that behaves well for one percent of users may strain a database at fifty percent. This is why gradual steps matter. Each step is a small load test performed on real traffic, with the ability to retreat. Watch response times and resource use at each step, and treat a slowdown as a reason to pause, not as an annoyance to push through.

Nobody starts with automated pipelines and approval gates. Good practice grows in stages, each one earned by a real need.

The maturity ladder

Teams tend to pass through recognisable stages as they adopt feature flags. Seeing the ladder helps you choose the next step instead of attempting the whole climb at once. Skipping rungs usually fails, because the habits of one stage are the foundation of the next.

Roles that help

Even small teams benefit from naming a few roles, though one person may hold several. The flag owner is accountable for a particular flag from creation to removal. The release owner coordinates what is promoted in each release. The reviewer approves Production changes and looks at the difference with fresh eyes. The on-call engineer holds the authority to switch flags off in an emergency. Writing these roles down removes the confusion of “I thought you were doing that”.

Measuring improvement

A few simple measures show whether your practice is getting better. Track how long it takes to roll out a flag from Staging to everyone in Production. Track how many flags are older than their planned removal date. Track how long a rollback takes from the moment someone decides to do it. Track how many Production flag changes were later reversed because they were wrong. None of these needs a special tool, and a monthly glance at them tells the team where to spend its next hour of improvement time.

Short, direct answers to the questions people ask most often when they first plan flag promotion.

Promoting a flag is a small act with large consequences. Treat it as a deliberate, repeatable routine and it quietly becomes one of the safest things your team does.