Before we copy anything, we need to know what we are copying. Let us start with the big picture of feature flags.

The problem feature flags solve

In the old days, a software team would finish a feature, bundle it with other changes, and release everything on one big day. If something broke, the only fix was to undo the whole release. That was slow, stressful and risky. Teams often called these days “release nights” because everyone stayed awake hoping nothing would fail.

A feature flag changes this. A flag is a small switch stored outside the code. The code says, “If this switch is on, show the new checkout page. If it is off, show the old one.” The new code can be shipped to everyone, hidden behind a switch that is off. Later, somebody flips the switch and the feature appears, with no new release at all. If it misbehaves, flipping it back takes seconds.

Where Flagsmith fits

Flagsmith is a feature flag and remote configuration service. “Remote configuration” simply means that besides on and off, a flag can also carry a value, such as a number, a piece of text or a small block of structured data. For example, a flag called “max_upload_size” could hold the number 25 in one place and the number 100 in another.

Flagsmith can be used as a hosted cloud service, or teams can run it themselves on their own servers or in their own cloud account. It is open source, which means its source code is public. It was originally known by another name, Bullet Train, before being renamed Flagsmith. It offers a web dashboard for people, an API for automation, and software development kits, usually called SDKs, for many programming languages.

What Flagsmith manages for you

Real-world context

Large technology companies have talked publicly about using flags for years. Facebook has described an internal system called Gatekeeper that controls who sees new features. Etsy became well known for deploying code many times a day while hiding unfinished work behind configuration switches. GitHub has shared that it uses feature flags to release changes to staff first, then to small groups, then to everyone. The idea is the same everywhere: ship the code quietly, then reveal it carefully. Flagsmith gives smaller teams access to that same style of working.

Cloning only makes sense once you understand what an environment is and how it is arranged inside Flagsmith.

The three-level structure

Flagsmith organises everything in three layers. At the top is the organisation, which usually represents a company or a team. Inside an organisation you create one or more projects, and each project normally represents one product or application. Inside each project you create environments, which represent the stages that product moves through.

flowchart TD
    ORG["Organisation: Acme Corp"] --> P1["Project: Shopping App"]
    ORG --> P2["Project: Admin Portal"]
    P1 --> F["Features defined once per project"]
    P1 --> S["Segments defined once per project"]
    P1 --> E1["Environment: Development"]
    P1 --> E2["Environment: Staging"]
    P1 --> E3["Environment: Production"]
    E1 --> V1["Own flag states and values"]
    E2 --> V2["Own flag states and values"]
    E3 --> V3["Own flag states and values"]

Notice something important in the picture. A feature, such as “new_checkout”, is created once for the whole project. But what that feature does in each environment, whether it is on, which value it holds, and which groups of users see it, is stored separately per environment. The feature is the name of a light switch. The environment decides whether that switch is up or down in each room.

Why teams keep separate environments

Different stages of work have different needs. Developers want to experiment freely, so they keep most flags on in the development environment. Testers want a stable copy that behaves like the real thing, so they use staging. Customers only ever touch production, and production must be changed with care. If all three shared one set of switches, a developer turning on an unfinished feature could expose it to real customers by accident.

What each environment owns

• Its own keys. Each environment gets an identifier that applications use to say, “Please give me the flags for this environment.” There are also separate server-side keys for trusted backend services.
• Its own flag states. The enabled or disabled setting and the stored value of every feature.
• Its own segment overrides. Rules that change a flag for certain groups of users.
• Its own identities. Records of individual users and their traits, such as a plan type or a country.
• Its own settings. For example, who may approve changes, and whether sensitive data is hidden from viewers.

Typical environment layouts

Cloning is easy to describe in one sentence, but the details matter. Let us define it carefully.

A simple definition

Environment cloning means creating a new environment that begins with the same flag configuration as an existing environment. You pick a source environment, give the new one a name, and Flagsmith copies the settings across. The result is a separate environment, with its own new keys, that you can then change freely without touching the original.

Cloning versus creating from scratch

When you create a blank environment in Flagsmith, every feature in the project appears in it with default settings, usually disabled. If your project has five features, that is quick. If your project has four hundred features, a blank environment means someone must walk through hundreds of switches and set each one by hand. That is slow and easy to get wrong.

A clone saves that effort. Flags that should be on are already on. Values that should be 100 are already 100. Rules for special groups are already in place. You start from a known good state rather than an empty one.

Cloning versus copying values by hand

Some teams try to avoid cloning by writing scripts that read one environment and write to another. This can work, but it takes time to build, needs maintenance and can miss details. Cloning is built into the product, tested by its makers, and does the whole job in one step.

Cloning is a snapshot, not a link

This point surprises many beginners. A clone is not connected to its source. It is a snapshot taken at the moment you press the button. If you later change a flag in the source, the clone does not change. If you want the clone to match the source again, you either clone again into a fresh environment or you update the differences yourself.

Cloning is not a trick for its own sake. It solves real problems that appear as products and teams grow.

Use case 1: Spinning up a staging copy of production

Use case 2: Preview environments for each code change

Use case 3: Launching in a new region or for a new customer

Use case 4: Training, demos and sales

Use case 5: Rehearsing a risky change

Use case 6: Recovering from mistakes

This is the most important chapter for avoiding surprises. A clone copies the flag configuration, not everything that exists around it.

The simple rule of thumb

Cloning copies configuration, meaning the decisions people made about how features behave. It does not copy live data, meaning the records created by real users and real traffic, and it does not copy secrets, meaning the keys that let software talk to the environment.

The comparison table

Why identities are left out

Identities are records of real people, such as “user 48213 lives in Canada and has the premium plan”. They are created by live traffic. Copying them into a test environment would spread real customer information into a place with weaker protection. Leaving them out is a safe default, and it also keeps clones small and fast.

Why keys are not copied

If keys were copied, two environments would answer to the same identifier and applications could not tell them apart. A key is like an address. Two houses cannot share one address. Every clone gets its own, which also means a leaked development key never exposes production.

Why history is not copied

An audit log answers the question, “Who changed what, and when, in this environment?” A clone is a new environment, so its story begins on the day it was created. Starting with an empty log keeps the record honest.

A short checklist after any clone

• Compare ten or so important flags between the source and the clone.
• Check that segment overrides are present for any rule-based flags.
• Copy the new environment key into the application settings meant for it.
• Review integrations and webhooks for anything that still points at the source.
• Check who has permission to the new environment.

To understand how cloning works, we need to meet the building blocks it moves around.

The building blocks

How the pieces relate

Picture a grid. Down the side you list every feature in the project. Across the top you list every environment. Each cell of the grid is a feature state. A clone creates a new column and fills it with the same values as an existing column. Segment overrides are extra notes attached to certain cells, saying “for this group, do something different”. Cloning copies those notes too.

flowchart LR
    PRJ["Project"] --> FEAT["Feature: new_checkout"]
    PRJ --> SEG["Segment: Premium Users"]
    PRJ --> ENV["Environment: Staging"]
    FEAT --> FS["Feature State: enabled, value 100"]
    ENV --> FS
    SEG --> SO["Segment Override: enabled, value 200"]
    ENV --> SO
    FEAT --> SO
    ENV --> ID["Identities and Traits"]
    ID --> IO["Identity Overrides"]

The services that surround the data

Flagsmith is made of several cooperating parts. There is a web dashboard where people click buttons. There is an API, which is a doorway that software uses to read and change data. There is a database that stores everything durably. In many setups there is also a fast read layer, such as a cache or an edge service, that answers flag requests from applications very quickly without disturbing the main database.

Cloning happens on the management side. A person or a script asks the API to create a new environment based on an existing one, and the application code that evaluates flags is not involved at all. That separation is a key design idea: management traffic is small and careful, while flag-reading traffic is huge and fast.

A word about scale

Flag-reading traffic can be enormous. A popular mobile app might ask for flags every time a screen opens, which can reach millions of requests per minute across a user base. Management actions like cloning happen a few times a day at most. Flagsmith designs for both by keeping the two paths apart, so cloning a big environment does not slow down the apps that depend on flags.

Let us follow a clone request from the moment you press the button to the moment the new environment is ready.

The journey in plain steps

sequenceDiagram
    participant U as User or Pipeline
    participant D as Dashboard or API Client
    participant A as Flagsmith API
    participant P as Permission Check
    participant DB as Database
    participant C as Read Cache or Edge Layer
    U->>D: Request clone of Staging as Preview-42
    D->>A: Clone request with source and new name
    A->>P: Is this user allowed?
    P-->>A: Allowed
    A->>DB: Create environment and new keys
    A->>DB: Copy feature states
    A->>DB: Copy segment overrides and variations
    DB-->>A: Saved as one unit
    A->>C: Publish new environment data
    A-->>D: New environment details
    D-->>U: Preview-42 is ready

Why all-or-nothing matters

Databases offer something called a transaction. A transaction groups several writes together so they succeed or fail as one. Think of paying at a shop: either the money leaves your account and you get the item, or neither happens. If a clone failed halfway and left an environment with only half its flags, someone might test against it and trust wrong answers. Treating the clone as one unit prevents that.

Time and size

The time a clone takes grows with the number of features and overrides. A project with a few dozen features clones almost instantly. A project with thousands of features and many segment overrides takes longer, because every one of them is a row to copy. For that reason, teams with very large projects often keep the number of features trimmed by removing old flags regularly. A tidy project clones faster and is easier to understand.

What happens to the apps already running

Nothing, and that is the point. Applications talking to the source environment keep using the source keys and see no change. Only software configured with the new keys sees the new environment. This is why cloning is safe to do during working hours.

For most people the first clone happens with a mouse. Here is the shape of that journey. Labels can vary a little between versions.

Before you begin

• Make sure you have permission to create environments in the project. Project administrators usually do.
• Decide on a clear name for the clone, such as “Staging-Copy-Nov” or “Preview-Checkout-Redesign”.
• Decide which source is the best starting point. A calm staging environment is often better than production.
• Confirm that your plan allows the number of environments you want. Some plans limit this.

The steps

Doing it with automation

Flagsmith also offers an API for creating and cloning environments. Teams use it inside build pipelines, command-line helpers and infrastructure tools, so that a clone is created whenever a new test run starts. The details of the calls are in the official API reference, and a good habit is to keep the automation small: create the clone, run the checks, and delete the clone at the end. A pipeline that cleans up after itself prevents hundreds of forgotten environments from piling up.

A clone has a life of its own. It is born, used, drifts away from its source, and eventually retires. Understanding each stage helps you plan.

Stage 1: Birth

The clone appears with new keys and a copy of the source’s flag configuration. Its audit log is empty, and its usage numbers sit at zero. At this moment it is the most faithful it will ever be.

Stage 2: Connection

Applications are pointed at the new environment by giving them the new key. This might be a test build, a preview website or a sandbox. From now on, those applications ask Flagsmith for flags and receive answers from the clone.

Stage 3: Use and change

People begin to change flags in the clone. A tester turns on a new feature. A developer tries a different value. Each change is recorded in the clone’s own audit log, and none of it affects the source.

Stage 4: Drift

Meanwhile, the source keeps changing. Production teams flip flags as part of their normal work. The clone, frozen at its birth moment, falls behind. After a few weeks the two may differ in dozens of places.

Stage 5: Retirement

When the clone has done its job, it is deleted. Deleting removes its configuration and keys. Any application still pointed at those keys will start receiving errors or defaults, so confirm that nothing important depends on the clone first.

stateDiagram-v2
    [*] --> Cloned: Clone requested
    Cloned --> Connected: Apps given new keys
    Connected --> InUse: Flags changed by team
    InUse --> Drifting: Source keeps changing
    Drifting --> Refreshed: Re-clone or sync by hand
    Refreshed --> InUse
    InUse --> Retired: Work finished
    Drifting --> Retired: No longer needed
    Retired --> [*]

How flag requests reach a clone

When an application starts, its SDK, which is a small helper library, contacts Flagsmith with the environment key. There are two main styles of evaluation. In remote evaluation, the application asks Flagsmith for the answer each time, or on a schedule, and Flagsmith works out which flags apply to that user. In local evaluation, a trusted server-side application downloads the whole environment configuration once, keeps it in memory, and works out answers on its own, refreshing from time to time. Both styles work the same with cloned environments, because from the outside a clone is just another environment with its own key.

Refreshing a stale clone

If you want the clone to match the source again, you have two realistic choices. The first is to delete the clone and create a new one from the source. This is clean and fast, but you lose any changes you made in the old clone. The second is to compare the two environments by eye or by script and update the differences. The second takes longer but keeps the clone’s own work. Many teams choose the first for short-lived environments and the second for long-lived staging.

Flags are not always a simple yes or no. Cloning has to carry the clever parts too.

What segments are

A segment is a named group of users defined by rules. For example, “Beta Testers” might mean users whose trait “beta” is true, and “India Premium” might mean users whose country is India and whose plan is premium. Segments are written once at the project level and can be reused in every environment.

What segment overrides are

A segment override says, “In this environment, for this segment, give this feature a different setting.” Suppose the feature “new_dashboard” is off for everyone, but on for Beta Testers. That second part is a segment override. If a segment has overrides on many features, the clone needs to copy every one of them, or the new environment would behave differently for important groups.

Priority and order

When several segments apply to one person, Flagsmith decides which override wins. Overrides are ranked, and the highest one that matches decides the answer. Cloning keeps those rankings, so the order of precedence in the clone matches the source.

Multivariate flags

A multivariate flag has several possible values with a percentage split. Imagine a button colour test where 50 percent of visitors see blue, 30 percent see green and 20 percent see orange. A clone starts with that same split. This is useful for rehearsals, but be careful: if your clone shares real visitors with the source by mistake, you may accidentally run the test twice and muddy your results.

Identity overrides stay behind

Sometimes a product manager gives one named person special access, such as an executive who wants to see a feature early. That is an identity override, and it belongs to that person’s record in the original environment. It does not travel in a clone. If you need the same person to have special access in the clone, add it again on purpose.

A worked example

A table of what to double-check

Copying configuration sounds harmless, but it can spread more than you intend. A little care protects both customers and your company.

Know your two kinds of keys

Each environment has a client-side key, which is meant to be placed inside apps that run on user devices, such as web pages and mobile apps. Because users can find it, it is not a secret and it only allows reading flags. There are also server-side keys, which are meant for trusted backend software only. They can do more, including downloading the whole environment for local evaluation, so they must be kept secret. A clone gets its own set of both kinds.

Control who can clone and who can see

Flagsmith lets you grant permissions at several levels: organisation, project and environment. A sensible setup lets many people view and edit development environments, fewer people edit staging, and only a trusted few edit production. When you create a clone, check who has access to it. A clone of production sometimes carries sensitive values such as internal addresses or partner settings in its flag values. Those values may now sit in an environment with looser access.

Watch what is stored in values

Remote configuration values are convenient, but they are not a vault. Passwords, private keys and secret tokens should never be stored as flag values. If someone already did that in production, a clone spreads the mistake. Use a proper secrets manager for secrets and keep flag values to harmless settings.

Use the hide-sensitive-data option when available

Flagsmith offers an environment setting that hides flag values from certain views and responses, which is helpful when an environment holds values you do not want widely seen. Check whether the setting carried over to your clone and turn it on where needed.

Approvals for important changes

On plans that offer them, change requests and approval rules let a second person review a flag change before it takes effect, similar to a code review. If your source environment demands approvals, make sure your clone either has the same rule or has a good reason not to. A clone with no approvals can be a hidden side door if it is ever connected to something important.

Customer data and privacy

Because identities and traits are not copied, cloning does not duplicate your users’ personal information. That is a real privacy benefit. Do not undo it by importing real user records into test environments. If you need realistic test users, create fake ones.

When many environments exist, the ability to answer “what changed, who did it and when?” becomes extremely valuable.

The audit log

Flagsmith records changes in an audit log. When someone flips a flag, edits a value or adds an override, a line appears with the person’s name, the time and the change. Each environment has its own trail. That is why a clone starts with a clean log: the log tells the story of that environment alone.

When something odd happens, the audit log is the first place to look. If checkout suddenly changes in staging, a quick look shows that someone enabled a flag twenty minutes ago.

Integrations and webhooks

Flagsmith can send information to other tools when things change. A webhook is a message sent automatically to a web address whenever a certain event happens, such as a flag change. Teams use them to post notices in chat tools, create tickets or trigger tests. Some teams also connect analytics and monitoring tools. After a clone, check whether these connections exist for the new environment. A missing one means silent changes; a wrong one might send test notices to the production channel.

Usage and traffic numbers

Flagsmith can show how many times flags were requested, which helps spot environments that nobody uses anymore. A clone begins with zero. If a clone shows traffic you did not expect, something is pointing at it that should not be.

Naming and tagging for visibility

Good names make monitoring easy. Use patterns such as “preview-pr-1234”, “demo-acme-nov” or “staging-eu”. Flagsmith also supports tags on features, which let you label flags by team, risk or lifecycle. Tags are applied per feature at project level, so they appear the same in every environment.

Every tool has a price. Cloning is wonderful, but it is not free of costs.

The trade-off between freshness and stability

A clone made from a very recent copy of production is fresh but may carry half-finished experiments. A clone made from a calm template is stable but may be missing recent changes. Choose based on the question you are trying to answer. If you are chasing a bug that appears in production, clone production. If you are rehearsing a new feature, clone a quiet template.

The trade-off between many small environments and a few big ones

Short-lived per-change environments give excellent isolation. Each test sees only its own settings. But they add moving parts and require tidy-up automation. A few shared long-lived environments are simpler to manage but cause people to step on each other’s changes. Teams often use both: a few shared environments for general work and temporary clones for risky or parallel work.

The trade-off between clone and sync

Patterns are habits that other teams have already tested. Anti-patterns are habits that looked clever and then caused pain.

Pattern 1: The golden template

Keep one environment whose only job is to be a clean, well-reviewed starting point. Nobody sends real traffic to it. When you need a new environment, you clone the template. Because it never gets messy experiments, every clone starts healthy. Update the template deliberately, after each major release, so it stays current.

Pattern 2: The disposable preview

For every code change under review, an automated step clones the template, runs the tests with the new keys, reports the results and deletes the clone. Nothing is left behind. This gives each change a private playground and prevents tests from fighting each other over shared flags.

Pattern 3: The regional family

For products that run in several regions, create one well-tuned region first, then clone it for the others and adjust only the values that differ. Keep a short written list of what is allowed to differ between regions. This makes it easy to spot accidental differences later.

Pattern 4: The rehearsal clone

Before a high-stakes release day, clone production, perform the full plan of flag changes in the clone, check the result, and only then perform it live. Record what you learned, and fix the plan if something surprised you.

flowchart TD
    T["Golden Template Environment"] --> C1["Clone: Preview for Change 101"]
    T --> C2["Clone: Preview for Change 102"]
    T --> C3["Clone: Regional Copy EU"]
    T --> C4["Clone: Demo for Sales"]
    C1 --> X1["Run tests then delete"]
    C2 --> X2["Run tests then delete"]
    C3 --> L["Long-lived with its own owner"]
    C4 --> X4["Delete after demo week"]

Anti-pattern 1: Cloning production for everything

Anti-pattern 2: The forgotten clone farm

Anti-pattern 3: Trusting a stale clone

Anti-pattern 4: Secrets in flag values

Here are the habits that experienced teams build around cloning, and the slips that beginners make most often.

Best practices

Common mistakes

A quick troubleshooting guide

Cloning is one tool in a toolbox. Knowing the other tools helps you pick the right one for each job.

Option 1: Build a blank environment and fill it by hand

This is the slowest path, but it gives you total control. Every feature appears in the new environment with default settings, and you walk through them one by one. It makes sense when the new environment is meant to be very different from every existing one, for example a brand-new product line that happens to share a project, or when you want to prove that nothing unwanted came along from a messy source.

Option 2: Clone an existing environment

This is the fast path and the subject of this guide. It is best when the new environment should start out close to an existing one. You change only the differences afterward.

Option 3: Script the setup through the API

Flagsmith exposes an API that can read and write flag settings. A team can write a small program that reads the desired settings from a file kept in their code repository and applies them to an environment. This approach has one big advantage: the settings are written down in a file that people can review, compare and keep a history of. It also has a cost: someone must write and maintain the program, and it must be updated whenever Flagsmith adds new kinds of settings.

Option 4: Describe environments with infrastructure tools

Some teams describe their cloud resources in text files, using what is called “infrastructure as code”. Tools of this kind can create servers, databases and networks from written descriptions, and community or vendor-provided plugins exist for various services. A Flagsmith provider for such a tool allows environments and features to be described in the same way. The benefit is repeatability and review. The cost is a learning curve and the need to keep the descriptions in step with changes people make by hand in the dashboard.

Option 5: Use the command-line helper to download and reuse data

Flagsmith provides a command-line helper that can fetch the flag data of an environment and save it in a file. That file is mainly used so that applications can start with a known set of flags even when the network is down, but it is also a convenient way to take a look at the settings of an environment offline and compare two of them.

A comparison table

How to choose

If you only create a new environment once in a while, cloning is almost always enough. If you create many environments every day, add some automation around cloning. If you have strict rules that every setting must be reviewed before it takes effect, keep the settings in files and use cloning only for throwaway environments.

Products that serve millions of users need flag systems that stay fast and stay up. Here is how cloning fits into that picture.

Two very different kinds of traffic

Flagsmith deals with two kinds of work. The first is flag reading: applications asking, “What are my flags?” This happens constantly. A large consumer app might send thousands of such requests every second at busy times. The second is management: people and pipelines creating features, flipping switches and cloning environments. This happens occasionally. Good design keeps the two apart so that a burst of management work never slows down flag reading.

How reading stays fast

Flag data is read far more often than it changes. That pattern is perfect for caching, which means keeping a ready copy of popular answers close to where they are needed, so they do not have to be worked out again. Flagsmith’s managed service uses a separate, fast read layer at the edge of the network, so applications talk to a nearby server instead of the main database. Self-hosted setups can add their own caches in front of the API. SDKs also keep results in memory for a short time, so a single application does not repeat the same request again and again.

What a clone does to the read layer

When a clone is created, its data must also appear in the fast read layer so applications can ask for it. There may be a short delay, a matter of moments, before the new environment answers requests from every location. Pipelines that create a clone and immediately run tests should therefore wait until the new environment responds correctly before starting the tests, instead of assuming it is ready the very instant the clone call returns.

Size matters

The amount of work in a clone depends on how many features and overrides the project holds. A project with 50 features and a handful of overrides is trivial. A project with 3,000 features and thousands of overrides is a bigger job, and each environment in that project also makes every flag-reading response a little heavier. This is one of the strongest reasons to retire old flags.

High availability: what if Flagsmith itself has a bad day?

Because flags control behaviour, a flag service outage could matter. Good teams plan for this in three layers. First, SDKs can be configured with default values in the code, so if the service cannot be reached, the app falls back to sensible behaviour. Second, SDKs can keep a recent copy of flag data, so the app keeps working with slightly old answers. Third, the service itself can be run in several places, with data stored in a database that has a standby copy ready to take over.

Scaling cloning itself

If a pipeline creates a fresh clone for every code change, and a hundred changes arrive in an hour, you will have a hundred clones. That is fine for the system if each is deleted promptly, but it can run into plan limits or rate limits. Teams solve this by sharing a small pool of reusable preview environments, by cleaning up aggressively, or by cloning only for changes that touch flag-related code.

Where Flagsmith runs changes what cloning feels like in daily life. Let us look at the main choices.

The hosted service

Flagsmith offers a hosted service where the company runs everything. You sign up, create a project and start working. Updates arrive automatically, performance tuning is handled for you, and the read layer is already spread across the world. Cloning in the hosted service is a matter of using the dashboard or API. Limits depend on your plan, including how many environments or projects you can have.

Self-hosting

Because Flagsmith is open source, a team can run it on its own servers or in its own cloud account. Common ways include containers started with a container tool and packaged installs for container-orchestration systems such as Kubernetes. A self-hosted setup needs a database, usually PostgreSQL, and one or more copies of the API service. Teams choose this path when they must keep data inside their own network, when rules forbid sending certain data outside, or when they want complete control.

What changes for cloning

• Database load. A clone writes many rows. On a self-hosted system, make sure your database has room to handle bursts, especially if pipelines create many clones at once.
• Background work. Some actions in Flagsmith are handled by background workers. Make sure workers are running and healthy, or follow-up tasks after cloning may be delayed.
• Backups. You own the backups. A scheduled database backup is your real safety net, not a clone.
• Upgrades. When you upgrade Flagsmith, new settings may appear. After an upgrade, clone once into a test environment and verify the result.
• Access. You decide who can reach the dashboard, usually behind your company login system.

flowchart LR
    DEV["Developer or Pipeline"] --> LB["Load Balancer"]
    LB --> API1["Flagsmith API Copy 1"]
    LB --> API2["Flagsmith API Copy 2"]
    API1 --> DB[("Primary Database")]
    API2 --> DB
    DB --> STBY[("Standby Database")]
    API1 --> CACHE["Cache Layer"]
    API2 --> CACHE
    APPS["Applications using SDKs"] --> LB
    API1 --> WORK["Background Workers"]
    API2 --> WORK

Private cloud and hybrid styles

Some vendors offer a private installation, where the service is run for you but in a space dedicated to your company. This gives some of the comfort of the hosted service along with isolation. Companies with strong rules often use this middle path.

Cost thinking

Cloning itself costs almost nothing in compute. The real costs are indirect: plan tiers that charge by number of projects or requests, the time people spend maintaining many environments, and the storage that old clones occupy. A tidy habit of deleting temporary clones keeps all three low.

Multi-region and multi-cloud

Large companies often run products in several regions. Flagsmith can be deployed in more than one place, but a single environment lives in one Flagsmith installation. If you want an identical set of flags in two installations, a clone does not cross that boundary, because it only works inside one project of one installation. Teams handle this with scripts that read from one and write to the other, or by keeping the settings in files. Always plan for this early if you operate across several clouds.

Things go wrong. The aim here is to know the usual troubles in advance and to have a calm response ready.

Scenario 1: The clone call fails halfway

Because the copy is done as one unit, the usual result is that nothing was created. Check the environment list. If nothing new appears, simply try again. If something partial does appear, delete it and start again, then report the problem to your administrator or to Flagsmith support, because partial results are not expected behaviour.

Scenario 2: The clone looks right, but the app behaves differently

This almost always means the application is still using the old key, or a setting that was not copied is involved. Check the key first. Then check segment overrides, identity-specific rules and integrations.

Scenario 3: A clone was accidentally given real traffic

Someone put the clone’s key in a live app. Customers now see test settings. Fix this by swapping back to the correct key at once, and then look at the audit log of the clone to see what, if anything, was changed. Add a rule in your review process that production configuration changes need a second pair of eyes.

Scenario 4: The wrong environment was deleted

Deleting an environment is serious. Its configuration and keys are removed, and applications using it begin to fail. If you have a recent clone, you can create a new environment from it and restore most of the flag settings, though the keys will be new and must be updated in every application. This is the best argument for using clear names, restricting delete rights and keeping periodic backups on self-hosted installations.

Scenario 5: Plan limits stop a clone

The error says you have reached the environment limit. Look for forgotten clones to delete, or ask an administrator about a higher plan. Do not delete anything you are unsure about.

Scenario 6: A source changed during the clone

If someone flips a flag in the source at the very moment you clone it, the clone may include the change or not. For routine uses this is unimportant. For a critical rehearsal, agree on a short freeze on the source while the clone is made.

flowchart TD
    S["Something looks wrong"] --> Q1{"Is the app using the right key?"}
    Q1 -- "No" --> F1["Swap in the correct key and restart"]
    Q1 -- "Yes" --> Q2{"Do the flag states match the source?"}
    Q2 -- "No" --> F2["Re-clone or fix the differences"]
    Q2 -- "Yes" --> Q3{"Are overrides and segments right?"}
    Q3 -- "No" --> F3["Copy the missing override by hand"]
    Q3 -- "Yes" --> Q4{"Do integrations point to the right place?"}
    Q4 -- "No" --> F4["Set the integration up again"]
    Q4 -- "Yes" --> F5["Check the audit log for recent changes"]

Recovery habits that pay off

• Use names that make mistakes harder, such as adding “PROD” in capital letters to production.
• Limit delete permission to a very small group.
• Keep a template environment as a spare reference.
• On self-hosted installations, test restoring from a database backup, not only taking one.
• Write a short runbook that explains how to create, verify and delete clones. A runbook is simply a checklist for a repeating task.

As more people use feature flags, rules and habits matter as much as buttons. This chapter covers the human side of cloning.

Who owns an environment?

Every environment should have an owner, a person or a team who answers questions about it. For long-lived environments, record the owner in a shared document. For short-lived clones, put an owner or ticket reference in the name. Unowned environments become mysteries after a few months.

A simple naming convention

Roles and permissions in practice

A workable model has three levels of trust. Everyone in engineering can create and edit temporary clones. A smaller group can edit shared staging environments. A very small group, often those on call, can edit production. Clones made from production inherit sensitive values, so decide in advance whether they may exist at all, and if so who may view them.

Approvals and change control

Companies in finance, health and government often need proof that important changes were reviewed. Approval workflows on production environments give that proof. Make sure the approval setup is applied to any clone that is promoted to something more permanent. Temporary clones used for experiments can usually skip approvals, as long as they cannot affect real users.

Privacy and compliance

Rules such as the European data protection law and similar rules elsewhere care about personal data. Because cloning does not copy identities or traits, it is naturally friendly to those rules. Keep it that way. Avoid loading real personal data into test environments, and avoid storing personal data in flag values. If your company is audited, the audit log and the permission list are the first things reviewers ask to see.

Teaching new teammates

New joiners should learn four things in their first week: what each environment is for, how to clone safely, how to find the audit log, and how to ask for help. A one-page guide with screenshots from your own project, written in plain words, is worth more than a long manual.

Hand-offs between teams

A governance checklist

• Every environment has a written purpose and an owner.
• Production edit rights are limited and reviewed every quarter.
• Temporary clones are deleted within an agreed number of days.
• No secrets or personal data live in flag values.
• Approval rules are checked after any promotion of a clone.
• A runbook describes how to clone, verify and delete.

Let us follow a made-up online shop, “Acme Cart”, through a full launch to see how every idea in this guide fits together.

The situation

Acme Cart sells home goods to about two million monthly shoppers. The team has built a faster checkout and wants to release it carefully. They use Flagsmith with one project, “Shop”, and three long-lived environments: Development, Staging and Production. They also keep a quiet template environment called “template-base”.

Stage 1: Plan the change

Product, engineering and operations agree on the plan. A new feature called “fast_checkout” will be created. It will be enabled first for staff, then for a small segment of loyal customers, then for half of all shoppers, then for everyone. A kill switch called “fast_checkout_kill” will exist so that anyone on call can instantly turn the feature off.

Stage 2: Build and test in Development

Developers create the new features in the project. They appear in all environments, disabled by default. In Development, developers switch “fast_checkout” on and test freely.

Stage 3: Clone for rehearsal

Operations clones Production into a new environment named “rehearsal-checkout-q4”. They want to practise the exact sequence of changes against settings that match what customers see today. They give the new key to a test copy of the shop website. The clone has the same segments, overrides and values as production, but no customer records and no history.

Stage 4: Practise the rollout

In the rehearsal environment, the team enables the feature for the Staff segment, then for the Loyal Customers segment, then sets a percentage split. At each step, testers confirm the behaviour on the test site. They discover that an old override on a related flag, “legacy_discount_banner”, clashes with the new design. They fix the plan: the banner must be disabled at the same moment.

flowchart LR
    A["Plan the rollout"] --> B["Build features in Development"]
    B --> C["Clone Production into rehearsal"]
    C --> D["Practise each step and note problems"]
    D --> E["Fix the plan"]
    E --> F["Apply steps to Production with approval"]
    F --> G["Watch graphs and the audit log"]
    G --> H["Delete the rehearsal clone"]

Stage 5: Apply the plan in Production

With a corrected, proven plan, an engineer proposes the changes in Production. A second person reviews and approves them. At the agreed quiet hour, the steps are applied one at a time, with a pause between each to watch error rates and checkout success numbers on the monitoring dashboards.

Stage 6: Watch and learn

The team places the flag change times next to their graphs. When the percentage reaches half of shoppers, checkout speed improves as expected, and no new errors appear. They move to everyone a day later.

Stage 7: Clean up

The rehearsal clone is deleted. Two weeks later, the team removes the old checkout code, deletes the “fast_checkout” flag and keeps the kill switch for a while longer. The template environment is refreshed so that new clones include the final settings.

What went well, and why

The most common reason to clone is to test something safely. Here are the testing styles where a clone earns its keep.

Why flags make testing harder, and how clones help

A normal program has one behaviour. A program with ten flags has, in theory, over a thousand possible combinations, because each flag can be on or off. No team tests every combination. Instead, they test the combinations that matter most: the one that exists in production today, the one that will exist after the next release, and a few risky mixtures in between. A cloned environment gives each of those combinations a home with its own keys, so tests never disturb each other.

Style 1: Automated tests per code change

When a developer proposes a change, an automated pipeline builds the app, creates a clone from the template, hands the new key to the test run, runs the tests and deletes the clone. The result is a pass or a fail, linked to the change. If two developers propose changes at the same time, each gets their own clone and neither can disturb the other.

Style 2: Manual exploratory testing

Human testers like to wander through an app, trying odd things. A dedicated clone lets them switch features on and off as they explore, with no fear of leaking an unfinished feature to customers. After testing, they write notes and the clone is deleted or refreshed.

Style 3: End-to-end tests of important journeys

For journeys such as signing up, paying and cancelling, teams keep a longer-lived environment that mirrors production closely. It is cloned from production on a schedule, such as once a week, so the tests run against settings that match reality. When the tests fail, it is a signal that either the code or the settings have changed in a risky way.

Style 4: Load and performance tests

Before a big sale or launch, teams simulate heavy traffic. A clone of production lets them do this with the same flag settings real shoppers experience, without sending test traffic to the production environment’s counters and logs. Be careful that the test traffic uses the clone’s key, and that the test only sends fake users.

Style 5: Chaos and failure drills

Some teams practise what happens when a flag service is slow or unreachable. In a clone, they can deliberately remove defaults, change values to unusual numbers or switch off kill switches, and watch how the application copes. The point is to learn about weak spots in a safe place.

Style 6: Experiment design checks

Before running a real experiment, such as a three-way test of a new button, analysts test that the percentages add up, that the right segments are included, and that the app reports results correctly. A clone gives them a dry run of the experiment, using fake users.

What a good test environment checklist looks like

• It was created from a known source, and the source is written down.
• It uses its own keys, stored safely.
• It contains only fake users.
• Its permissions are limited to the people doing the testing.
• It has an expiry plan.
• Someone owns it.

Once the basics feel comfortable, a few deeper ideas decide how well cloning scales in a big organisation.

Environment-level settings

Besides flag states, each environment carries its own settings. Examples include whether sensitive data is hidden, whether client applications may store traits about users, how many approvals a change needs, and details of how identities are recognised. Which of these are carried across by a clone depends on the version, so after cloning, open the settings page of the new environment and compare it with the source, line by line. Doing this once and writing down the result gives you a trusted answer for your version.

Feature versioning

Some versions of Flagsmith offer a feature that keeps numbered versions of each flag’s settings in an environment, so you can see earlier states and prepare changes to go live at a chosen time. If this is turned on in the source, check how it behaves in the clone. A fresh clone usually starts its own history at its birth, so earlier versions from the source do not appear.

Scheduled changes

Planned changes, such as “turn this on at nine o’clock on Monday”, belong to the environment where they were set. A clone should not be expected to inherit planned changes. After cloning, check whether any schedule needs to be set again, and be careful not to leave two environments scheduled to do the same thing by accident.

Tags and organisation of features

Tags are labels on features, such as “team-payments” or “temporary”. They live at the project level, so every environment sees the same tags. Good tagging makes clean-up easier: you can list all features tagged “temporary” and ask the owners whether they are still needed. Cleaner projects make clones faster and easier to review.

One project or many?

Teams often wonder whether to put several products in a single project or give each its own. The answer affects cloning, because cloning works inside one project.

Promoting changes between environments

Cloning moves a whole environment’s configuration at once. Often what you really want is to move just one change from staging to production. That is a different task, called promotion. Promotion is usually done by applying the same small change in the next environment, by hand or through a script, often with an approval. Understanding this difference prevents a classic mistake: using a clone as a shortcut for deploying a single flag, which can quietly overwrite many other settings.

Flag lifecycle

Flags are not meant to live forever. A healthy flag goes through stages: created, tested, rolled out, fully on, removed from code, deleted. Cloning copies flags at whatever stage they are in. If your template contains dead flags, every clone does too. Make flag removal a normal part of finishing a feature, and your clones stay light.

stateDiagram-v2
    [*] --> Created
    Created --> Testing: Switched on in Development
    Testing --> RollingOut: Enabled for small groups
    RollingOut --> FullyOn: Enabled for everyone
    FullyOn --> CodeRemoved: Old code deleted
    CodeRemoved --> Deleted: Flag removed from project
    Deleted --> [*]
    RollingOut --> Testing: Problem found

Measuring success

Teams that use cloning heavily like to track a few simple numbers: how many temporary environments exist, how old the oldest one is, how long a clone takes, and how often a clone-related mistake reaches production. Reviewing these once a month helps catch bad habits early.

Cloning is one small feature of a larger way of working. Here is how the ideas around it show up at companies people know. The descriptions below are based on what these companies have discussed publicly, and they illustrate patterns, not details of any private setup.

Netflix: practising before the real show

Netflix has talked openly about canary releases, where a new version is first given to a tiny slice of traffic and compared with the old version before it reaches everyone. The thinking behind it is the same as a rehearsal clone: try the change somewhere safe, measure, and only then roll out widely. A cloned environment is the flag world’s version of that careful first step.

Facebook: gates for new features

Facebook has described how new features are released to employees first, then to small percentages of users, using an internal gating system. Each stage is a different audience with different settings. When you clone an environment and then change only a few values, you are following the same idea at a smaller scale: start from a known state and change the least you can.

Etsy: deploy often, reveal slowly

Etsy became known in the engineering community for deploying very frequently while hiding unfinished work behind configuration switches. For such teams, being able to set up a fresh, predictable test environment in moments makes frequent deployment less scary.

GitHub: staff first

GitHub has written about releasing features to its own staff before the public. A cloned “staff preview” environment, with a few extra features switched on, is a natural way to give staff a place to try things without disturbing real customers.

Google: change is the usual suspect

Google’s reliability practices emphasise that most outages follow some kind of change. That is why recording flag changes in an audit trail and rehearsing risky changes in a copy are such valuable habits. They shorten the time between “something broke” and “we know what changed”.

Uber-style regional operations

Companies that run in many cities and countries, as ride and delivery platforms do, need rules that differ by place: prices, features, legal requirements. A regional family of environments cloned from a well-tuned base keeps the shared parts consistent while letting each region adjust its own details.

A small-team example from start to finish

Experienced pilots do not trust memory for routine steps, and neither should you. These checklists turn the lessons of this guide into short routines you can copy into your own team wiki.

Before you clone

• Write one sentence describing why the clone is needed and who will use it.
• Choose the source on purpose. Prefer the quiet template unless you must reproduce production.
• Choose a clear name that shows purpose and, where useful, an owner or ticket number.
• Confirm that your plan has room for another environment.
• Decide the expiry date now, while you remember why the environment exists.
• Check that no important change is half-finished in the source.

Right after you clone

• Open the new environment and confirm the name and the project are what you expect.
• Compare at least ten important flags, including one with a value and one with a segment override.
• Compare environment settings: hidden values, approvals, trait handling.
• Look at integrations and webhooks. Re-create the ones the clone needs. Remove or avoid any that would send noise to live channels.
• Review the permission list. Remove access that is not needed.
• Store the new keys in your secrets tool and give them only to the apps that need them.

While the clone is in use

• Remind everyone using it that it is not production, and that changes in it will not affect the source.
• Keep notes of any change you may want to repeat in the real environment.
• Glance at the request counts now and then. Surprising traffic is a warning sign.
• If the clone lives longer than planned, decide whether to refresh it or turn it into a proper long-lived environment with an owner.

Before you delete the clone

• Check that no application still uses its keys.
• Copy any useful findings into your notes, such as the final flag settings for a rehearsal.
• Check the audit log for anything that should be shared with the team.
• Confirm the name one more time. Deleting the wrong environment is the most painful mistake in this area.
• Remove its keys from the secrets tool and from any test configuration.

Once a month

• List all environments and compare them against your naming rules.
• Delete or hand over any that have no owner or no recent traffic.
• Review who can edit production and who can delete environments.
• Refresh the template environment and note what changed.
• Look for flags that have been fully on for a long time, and plan their removal.

Quick answers to the questions that come up most often.

A short reference for the words used in this guide. Keep it nearby when reading Flagsmith documentation.

Let us pull the whole story together in a few lines you can remember.