Before we talk about approvals, we need to understand how much power one small switch can have.

A flag is a remote control

A feature flag is a small switch kept outside the program’s code. The program asks, “Is this switch on?” and behaves differently depending on the answer. Because the switch lives in Flagsmith and not in the code, anyone with the right access can flip it, and the change takes effect within moments, without a new release.

This is wonderful for speed. A broken feature can be turned off in seconds. A new feature can be shown to ten percent of visitors, then fifty, then everyone. But the same power is dangerous in the wrong hands or at the wrong moment. Flipping the wrong flag in the production environment can switch off payments, show unfinished screens or send customers to the wrong page.

The cost of a bad change

Studies of outages at large technology companies repeatedly find that a large share of incidents follow some kind of change, whether a code release or a configuration edit. Flag changes are configuration edits, so they belong in that family. A flag change takes seconds to make and may take hours to understand, because afterwards nobody remembers who changed what and why.

Two ways to protect production

Teams usually protect important environments in two ways. The first is permissions: only trusted people may edit production. The second is review: even trusted people must have a colleague check their change before it goes live. Permissions answer the question “Who may touch this?” Review answers “Does a second person agree this is a good idea?” Change requests are Flagsmith’s tool for the second question.

The idea is simple. The details are where it gets interesting.

A plain definition

A change request in Flagsmith is a saved proposal to change one flag in one environment. Instead of the change going live at once, it waits. Other people can read it, discuss it and approve it. Once it has enough approvals, someone publishes it, and only then does the live flag change.

The parts of a change request

• A title and description. A short name and a few sentences explaining what is changing and why.
• The proposed change. For example, “turn on the new checkout” or “change the page size from 20 to 50”.
• The requester. The person who asked for the change.
• The approvers. The people, or groups of people, who are asked to review it.
• A status. Where the request is in its life, such as waiting, approved or published.
• An optional go-live time. A moment in the future when the change should take effect.

What a change request is not

It is not a chat message and not a ticket in a separate tracking tool, although it is often linked to one. It is not a backup of your settings. It is not a way to schedule everything on your calendar. It is a gate placed in front of selected changes, with a record of who proposed, who approved and when the change went live.

A before-and-after picture

Different teams want review for different reasons. Here are the most common ones.

Use case 1: Protecting production

Use case 2: Meeting audit and compliance rules

Use case 3: Planned launches

Use case 4: Sharing knowledge

Use case 5: Training new teammates

Use case 6: Separating duties

To understand where the approval gate sits, we need the layout of Flagsmith itself.

Organisations, projects and environments

Flagsmith organises everything in three layers. An organisation is usually a company or team. Inside it live projects, each normally a product. Inside each project are environments, such as Development, Staging and Production. Features, which are the named switches, are defined once per project. What each feature does, on or off and with which value, is stored separately in each environment.

flowchart TD
    ORG["Organisation"] --> PRJ["Project: Shopping App"]
    PRJ --> FEAT["Features and Segments"]
    PRJ --> DEV["Environment: Development"]
    PRJ --> STG["Environment: Staging"]
    PRJ --> PRD["Environment: Production"]
    DEV --> D1["Direct edits allowed"]
    STG --> S1["Direct edits allowed"]
    PRD --> P1["Approvals required"]
    P1 --> CR["Change Requests"]

A setting per environment

Change requests are controlled by an environment setting that says how many approvals a change needs. When the number is zero, or the feature is off, people edit flags directly as usual. When a number such as one or two is set, direct edits to the protected kinds of settings are replaced by the change request workflow. Because the setting is per environment, development stays quick while production stays guarded.

Plans and availability

Change requests, sometimes called approvals or four-eyes review, have generally been offered on paid or higher plans of the hosted service, and in the enterprise offering for self-hosted installations. Exact plan names and limits change, so look at the pricing and plan pages or ask Flagsmith before building a process around the feature.

What the feature touches

At its heart, a change request deals with feature states: the on or off setting and the stored value of one feature in one environment. Depending on version and settings, it can also cover the rules that change a feature for particular groups of users, called segment overrides. Which actions are guarded in your version is worth checking once and writing down.

A change request is a small system with a few moving parts. Let us meet each one.

The roles

The objects

• The live feature state. What customers see right now.
• The proposed feature state. What the requester wants it to become, stored beside the live one but not active.
• The change request record. The title, description, requester, approvers, decisions and status.
• The approval record. Who said yes, and when.
• The audit log entry. The permanent note, written when the change finally goes live.

How the pieces connect

flowchart LR
    REQ["Requester"] --> CRQ["Change Request Record"]
    CRQ --> PROP["Proposed Feature State"]
    CRQ --> APP1["Approver 1"]
    CRQ --> APP2["Approver 2"]
    APP1 --> APR["Approval Records"]
    APP2 --> APR
    APR --> PUB["Publish"]
    PROP --> PUB
    PUB --> LIVE["Live Feature State"]
    PUB --> AUD["Audit Log Entry"]

Why the live and proposed states are kept apart

Keeping the two apart means that the apps reading flags never see half-reviewed changes. The apps keep reading the live state. The proposal is only a draft until it is published. This is the key safety property of the whole feature.

Every request moves through stages. Knowing them tells you where to look when something seems stuck.

The stages

stateDiagram-v2
    [*] --> Open: Request created
    Open --> Approved: Enough approvals
    Open --> Deleted: Requester withdraws
    Approved --> Published: Publish now
    Approved --> Scheduled: Go-live time chosen
    Scheduled --> Published: Time arrives
    Approved --> Open: Changes needed
    Published --> [*]
    Deleted --> [*]

What can end a request early

A requester can withdraw a request that is no longer wanted. A request can also become out of date. For example, another change may have been published on the same flag in the meantime, so the proposal is now built on old information. In that case it is wise to close the old request and create a fresh one, rather than publish something that might undo newer work.

Time spent in each stage

In healthy teams most requests are reviewed within minutes during working hours. The longest delay is almost always the waiting stage, when nobody notices the request. Good teams therefore agree on how reviewers are alerted, and on how long a request may wait before somebody chases it.

Let us follow a request through the machinery, from the first click to the live change.

Step by step behind the scenes

sequenceDiagram
    participant R as Requester
    participant D as Dashboard
    participant A as Flagsmith API
    participant S as Database
    participant V as Approver
    participant C as Read Cache
    participant P as Apps and SDKs
    R->>D: Edit flag and request approval
    D->>A: Create change request
    A->>S: Store proposal and request record
    A-->>V: Notify approver
    V->>A: Approve request
    A->>S: Store approval record
    R->>A: Publish approved request
    A->>S: Swap live state and write audit entry
    A->>C: Refresh cached flag data
    P->>C: Ask for flags
    C-->>P: Return updated flags

Why the swap is one step

The final swap is done as a single database transaction, which is a group of writes that either all succeed or all fail. Think of paying in a shop: either the money leaves your account and you receive the goods, or nothing happens. For flags, it means apps never see a half-applied change, such as a switch turned on but its value not yet updated.

The read path stays untouched

Applications that ask Flagsmith for flags are not involved in approvals at all. They keep reading the live state from fast read layers. Approval work happens on the management side, which handles a few actions per minute, not millions. This separation keeps flag reading quick even if reviewers are slow.

This chapter walks through the usual path in the dashboard. Labels can vary a little between versions.

Part A: Switch on approvals for an environment

Part B: Create a change request

Part C: Review and approve

• Open the request from the list of open change requests.
• Read the title and reason, then compare the proposed settings with the live ones.
• Ask yourself: is this the right environment, the right value and the right moment?
• Check whether another request on the same flag is already open.
• Approve if you are satisfied, or write back with questions if not.

Part D: Publish and verify

• When the count of approvals is reached, publish the request or let the schedule do it.
• Open the live flag and check that it shows the new setting.
• Watch your monitoring dashboards for a few minutes.
• If something looks wrong, use your rollback plan, which may be another change request or an emergency path.

Doing it through automation

Flagsmith also exposes change request actions through its API, so pipelines and bots can create requests, for example when a release process wants to enable a flag after a successful deployment. The approval step itself still needs people. Automation should propose, and humans should approve.

Approval answers “should this happen?” Scheduling answers “when?” The two work well together.

Why schedule?

Some changes must happen at a precise time. A sale begins at midnight. A product is announced at a conference keynote. A regulation takes effect on the first day of the month. Scheduling lets you decide the moment in advance and have Flagsmith apply the approved change on time, without anyone logged in.

How it fits with approvals

A scheduled change goes through the usual review. After it is approved, instead of publishing at once, it waits for the chosen time. At that time, Flagsmith applies it just as if somebody had published it. The audit log notes that it was applied by the schedule.

Things to think about

A scheduled launch from start to end

An approval gate is only useful if you know exactly what it guards. Gaps are where surprises hide.

Generally covered

• Turning a feature on or off in the protected environment.
• Changing the stored value of a feature in that environment.
• Changes to settings for groups of users, in versions that include segment overrides in the workflow.

Things to check in your version

The weakest link: who can switch it off

If anyone can turn off the approval setting, the approval gate is only as strong as that person’s discipline. Limit the right to change environment settings to a small group, and review who is in it from time to time.

Treat the gate as one layer

The approval count is only half of the story. Who is allowed to take part matters just as much.

The three kinds of rights

• Update rights. Who may edit flag states at all.
• Create change request rights. Who may propose changes to a protected environment.
• Approve change request rights. Who may say yes.

Flagsmith lets administrators grant permissions at several levels: the organisation, the project and the environment. Permissions can be given to single users or to groups. Using groups is almost always better, because people join and leave teams.

A workable model for most companies

Avoiding rubber stamps

If the only person who can approve is the requester’s best friend at the next desk, the approval is a formality. Aim for approvers who have the knowledge to judge the change and enough distance to say no. For high-risk flags, include someone from the team that owns the affected system.

Approving your own request

Whether a person may approve a change they proposed themselves depends on settings and versions. For separation of duties it should not be allowed, or at least it should not count toward the minimum. Check how your version behaves and write the rule in your process document.

Group by responsibility, not by name

Create groups that describe a duty, such as “Checkout reviewers” or “Production approvers”, and put people in them. When someone leaves or changes teams, you update one group instead of dozens of individual settings.

Change requests are often chosen because of rules, not just habits. Here is how they support security and compliance work.

Separation of duties

Many security standards want two different people involved in important changes: one who makes it and one who approves it. Change requests give a built-in way to do this for flag settings, and the record shows both names.

Traceability

Auditors like to ask, “Show me how this change was approved.” A change request holds the requester’s reason, the approvers and the time. The audit log adds the moment the change went live. Together, they answer the question without anyone searching old chat messages.

Least privilege

The idea of least privilege says that people should have only the access they need. In flag terms: engineers who occasionally propose a change get the right to create requests, not to edit production directly.

Protect the approval path itself

• Use your company’s sign-in system, with multi-step verification, for the Flagsmith dashboard.
• Protect API keys that can act on production, keep them in a secrets manager and rotate them.
• Review the list of people who can change environment settings.
• Log and watch for changes to approval settings.

Privacy

Change request text is stored and visible to reviewers. Do not paste customer data, passwords or private keys into titles, reasons or values. Use ticket numbers and general descriptions instead.

A mapping to common requirements

A request that nobody notices is as bad as no request at all. Visibility is what makes the process work.

Telling approvers

Flagsmith can notify approvers, for example by email, when a request needs their attention. Teams usually add a second route: a message in their chat tool, sent through an integration or webhook. A webhook is an automatic message sent to a web address whenever a chosen event happens. Check which events your version can send and which integrations are available, then connect them to the place where reviewers already spend their day.

The audit log

The audit log is Flagsmith’s record of changes. When a change request is published, the log records the flag change and the people involved. Each environment has its own trail. When something strange happens in production, the audit log is the first place to look: it shows what changed, when and by whom.

Putting changes on the same timeline as everything else

Site reliability engineers, a practice popularised by Google, like to line up every change on one timeline: deployments, configuration changes, flag changes and incidents. When error graphs spike, the first question is “What changed just before?” If flag changes are posted to the same dashboard, the answer arrives in seconds. Integrations with monitoring tools can help here.

Useful measures

A short list of questions the records can answer

• Who proposed the change that turned on the beta page?
• Who approved it, and what did they see?
• When exactly did it reach customers?
• Was a scheduled change applied on time?
• Which requests are still open and for how long?

Flags are not always a simple yes or no. Real rollouts use groups, percentages and several environments.

Segments in a request

A segment is a named group of users defined by rules, such as “Beta Testers” or “India Premium”. A segment override changes a feature for that group in one environment. A staged rollout often means a series of requests: first enable for staff, then for beta testers, then for ten percent of everyone. Each step is a separate proposal with its own reviewer and its own pause for watching.

Percentage splits and experiments

In experiments, a flag may hold several values with a percentage split, for example 50 percent blue, 30 percent green and 20 percent orange. A request that changes those percentages affects who sees what. Reviewers should check that the numbers add up and that the change will not disturb an experiment already running.

The same change in many environments

Teams often move a change through Development, Staging and Production. Change requests belong to one environment, so the same change needs a request in each protected environment. This is by design: each environment has its own risks. To reduce repeated typing, copy the title and reason, and refer to the earlier request, such as “Same as the staging request from last Tuesday”.

flowchart LR
    DEV["Development: edit directly"] --> STG["Staging: edit or one approval"]
    STG --> PRD["Production: change request with approvals"]
    PRD --> WATCH["Watch dashboards"]
    WATCH --> OK["Keep the change"]
    WATCH --> BACK["Reverse with a new request or emergency path"]

Related actions

If a project was set up by cloning an existing environment, note that the approval settings may or may not come along with the clone. After cloning a production-like environment, open its settings and check the approval rule, so the new space is guarded in the way you intend.

When many people work on the same flag, their proposals can collide. Understanding how helps you avoid nasty surprises.

The classic collision

Two people open requests on the same flag on the same day. The first sets the value to 50. The second, who did not know about the first, sets the enabled switch to on, but their proposal also carries the old value of 20. When both are published in turn, the second one may quietly put the value back to 20.

How to avoid it

• Before creating a request, check the list of open requests for the same flag.
• Name requests clearly, including the flag name, so duplicates are easy to spot.
• Keep requests small and focused: one purpose per request.
• Close old requests that are no longer needed.
• When a request is old, create a fresh one instead of publishing the old one.

What reviewers should check

When reviewing, look at the proposal against the current live state, not against your memory. Ask whether anything has changed on this flag since the request was created. If the answer is yes, ask the requester to refresh the proposal.

Ordering several requests

Products serving millions of users need flag systems that stay fast and stay up. Here is how approvals fit into that picture.

Two kinds of traffic

Flagsmith handles flag reading, which is constant and heavy, and management actions, which are occasional. Approval actions belong to the second kind. A busy team might create a few dozen change requests a day, while the apps they serve might read flags millions of times a minute. Good design keeps the two paths separate, so approvals never slow readers.

Caching and edge copies

Because flags are read far more often than changed, Flagsmith relies on caching, which means keeping ready copies of answers near the place they are needed. The managed service serves reads from a fast layer close to apps. When a request is published, the fresh data is pushed to that layer. Self-hosted installations can add their own caches. SDKs keep results in memory for a short time too. The result is that a published change appears quickly, usually within seconds, though caches can add a short delay.

What a delay means for planning

Do not promise to the second that a scheduled change will reach every user. Plan for a small window, and avoid designs where two flags must change at exactly the same instant. If the order matters, make the app tolerate either order.

What happens if Flagsmith is down

Imagine the flag service has a bad day. Apps should still work. Good teams prepare in three layers. First, SDKs are given default values in code, so features fall back to a safe behaviour. Second, SDKs can keep a recent copy of flags. Third, the service itself can be run with extra copies and a standby database. During such an outage, you will not be able to create or publish change requests, so keep a plan for emergencies that does not rely on a working dashboard.

Scaling the process, not just the software

Software scales more easily than people. If a hundred engineers send requests to three reviewers, the reviewers become the bottleneck. Scale the process by adding approver groups per area, by training more reviewers, by splitting large projects into smaller ones and by reserving requests for changes that really need review.

Where Flagsmith runs changes a few practical details about change requests.

The hosted service

In the hosted service, Flagsmith runs everything. Updates arrive automatically, performance is managed, and the approvals feature depends on your plan. Notifications and integrations are mostly ready to use.

Self-hosting

Because Flagsmith is open source, a team can run it on its own servers or in its own cloud account, using containers or tools such as Kubernetes. Some advanced features, which may include approvals, can depend on an enterprise licence. Check what your self-hosted edition includes.

flowchart LR
    USERS["Engineers and Reviewers"] --> SSO["Company Sign-in"]
    SSO --> 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 --> MAIL["Email or Chat Notifications"]
    API2 --> MAIL
    API1 --> WORK["Background Workers for Schedules"]
    APPS["Applications using SDKs"] --> LB

Things to watch when self-hosting

• Background workers. Scheduled changes need workers that are running and healthy. A stopped worker means a late change.
• Clock accuracy. Servers must agree on the time. A badly set clock makes schedules fire at the wrong moment.
• Email delivery. If notification emails fail, approvers will not notice requests. Test it.
• Backups. Requests, approvals and audit entries live in the database. Back it up and practise restoring.
• Upgrades. After upgrading, create one test request and publish it to confirm the flow still works.

Cost thinking

The software cost of change requests is mainly the plan tier. The larger cost is people’s time. Measure how long reviews take, and tune the process so that review effort goes where the risk is highest.

Every control has a price. Change requests are valuable, but they are not free.

The trade-off between speed and safety

Every extra approval slows the change a little and protects it a little more. The aim is to place friction where it pays for itself. A typo fix in a development flag deserves no review. A change to a payment flag in production deserves at least one.

The trade-off between many small requests and few big ones

The trade-off between one approval and two

One approval gives most of the benefit at a modest cost. A second approval adds more delay and is worthwhile for the most sensitive systems, such as payments, safety or legal compliance. Beyond two, approvals tend to create a situation where each reviewer assumes the others will look carefully, so nobody does.

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

Pattern 1: Guard only what matters

Turn approvals on for production and for any environment that mirrors real customers. Leave development free. This keeps experiments quick and protects what matters.

Pattern 2: The reviewer rota

Create a rota so that on every working day, a few named people are expected to review requests promptly. A rota removes the “someone else will do it” problem.

Pattern 3: Small steps with pauses

Break big launches into small requests with built-in pauses to watch dashboards. Each step is easy to review and easy to undo.

Pattern 4: Template descriptions

Agree on a short template for the request text: what is changing, why, how to check, how to undo, who to call. Templates raise the quality of requests and speed up reviews.

Pattern 5: Scheduled launch with a watcher

For scheduled changes, assign a person to watch the dashboards at go-live time and have a tested undo plan.

These are the habits experienced teams build, and the slips beginners make most often.

Best practices

Common mistakes

Troubleshooting guide

Approvals are wonderful until the house is on fire. Every good process needs a plan for urgent changes.

The emergency problem

It is two in the morning. A new feature is crashing checkout. The fix is to switch one flag off, which takes a second, but the environment requires an approval and the only other approver is asleep. What now? A rigid process that blocks the fix is as dangerous as no process at all.

Plan the emergency path before you need it

• Kill switches. Create special flags whose only job is to turn a risky feature off. Give on-call engineers both the right to create and the right to approve changes for them.
• On-call approvers. Make sure a second approver is always reachable during on-call shifts, with a way to be paged.
• Break-glass access. A small, tightly watched group can bypass or temporarily relax the rule. Every use is recorded and reviewed afterwards.
• Review after the event. Whoever used the emergency path writes a short note the next working day explaining what and why.

flowchart TD
    I["Incident detected"] --> Q1{"Can a kill switch fix it?"}
    Q1 -- "Yes" --> K["On-call creates and approves a kill switch request"]
    Q1 -- "No" --> Q2{"Is a second approver reachable?"}
    Q2 -- "Yes" --> N["Normal request with fast review"]
    Q2 -- "No" --> B["Use break-glass path and record it"]
    K --> V["Verify on dashboards"]
    N --> V
    B --> V
    V --> R["Write a short review the next day"]

Other things that can go wrong

As more teams use Flagsmith, habits matter as much as settings. This chapter covers the human side.

Who owns a flag?

Every flag should have an owner: a person or a team who answers questions about it and decides when it is removed. Tags in Flagsmith can show ownership, such as “team-payments”. Reviewers should know which team to ask when a request touches a flag they do not own.

A simple request template

Response expectations

Agree a reasonable target. For example: normal requests get a first look within one working hour, urgent requests within fifteen minutes during on-call time. Write the target where people will see it, and watch whether it is met.

Different rules for different risks

Not all flags carry the same risk. Many companies classify flags into levels. Low-risk flags, such as a colour or a label, may need no approval in production. Medium-risk flags need one. High-risk flags, such as payment or privacy settings, need two or a named expert. Flagsmith’s approvals are set per environment, not per flag, so teams often handle risk levels through process, tags and reviewer choice.

Onboarding

New teammates should learn four things in their first week: which environments are protected, how to write a good request, how to review one, and what the emergency path is. A one-page guide with screenshots from your own project, in plain words, is worth more than a long manual.

Retrospectives

Let us follow a made-up online shop, “Acme Cart”, through a full launch to see how all the ideas fit together.

The situation

Acme Cart sells home goods to about two million monthly shoppers. It uses Flagsmith with one project and three environments: Development, Staging and Production. Production requires one approval, and two for payment flags. The team plans a festival offer called “festival_offer” that must go live at 08:00 India time on a Saturday.

Stage 1: Plan

Marketing, engineering and support agree on the plan. There will be three requests in Production: enable the offer for staff first, then for loyal customers, then for everyone at the scheduled time. A kill switch, “festival_offer_kill”, already exists and is known to all on-call engineers.

Stage 2: Build and test

Developers create the new flags, which appear in every environment, switched off. In Development, they switch the offer on and test freely. In Staging, one reviewer checks the offer pages.

Stage 3: Write the requests

On Thursday, a product manager writes three requests in Production using the team’s template. Each says what, why, when, risk, check, undo and contact. They pick the “Checkout reviewers” group as approvers.

flowchart LR
    A["Plan the launch"] --> B["Test in Development and Staging"]
    B --> C["Write three change requests"]
    C --> D["Reviewers check and approve"]
    D --> E["Staff step published"]
    E --> F["Loyal customers step published"]
    F --> G["Everyone step scheduled for 08:00 Saturday"]
    G --> H["Watcher monitors dashboards"]
    H --> I["Close requests and note lessons"]

Stage 4: Review

A senior engineer opens the first request and compares the proposed settings with the live ones. She notices that the banner value in the second request still uses last year’s text. She writes a comment, the product manager corrects it, and she approves. A second reviewer approves the payment-related flag after checking that the discount is capped. The third request is approved on Friday.

Stage 5: Publish in steps

On Friday afternoon, the staff step is published. Staff test the offer in the real shop and report two typing errors in the text, which are fixed with a tiny request. On Friday evening, the loyal customers step is published. A watcher checks the error rate and checkout success graphs for twenty minutes.

Stage 6: The scheduled step

At 08:00 on Saturday, the scheduled change is applied. The watcher on duty sees the spike in traffic and a small, expected rise in checkout time. Nothing breaks. The audit log shows each person and each time.

Stage 7: Learn and clean up

The team writes down what went well and what did not. Two weeks after the offer ends, they remove the old code and delete the flag. The kill switch stays in place for the next offer.

The quality of a review depends on the quality of the request. A clear request can be approved in two minutes. A vague one can waste an hour of everyone’s time.

What reviewers really need

Reviewers are usually busy people looking at many things. They need to answer four questions quickly: What is changing? Why? What is the risk? How do we undo it? If your request answers those four questions in plain words, you are already ahead of most teams.

A weak request and a strong request

Habits of good requesters

• Be specific. Name the flag, the environment and the exact new value.
• Be short. Five clear lines beat a page of rambling.
• Link to context. Point to the ticket, the plan or the design document, but also summarise the key point, since reviewers may not click.
• Admit uncertainty. If you are not sure about something, say so. Reviewers can help only with what they know about.
• Give a time and a time zone. Even for “now”, say when you plan to publish.
• Say who is watching. Name the person who will check the dashboards afterwards.

Habits of good reviewers

• Open the request, not just the notification.
• Compare against the live state.
• Write back with specific questions, not “looks odd”.
• Say what you checked when you approve, even in one line.
• Say no politely when something is unsafe, and offer a better path.

Examples of good comments

Approvals are one of several ways to keep flag changes safe. Understanding the others helps you choose a sensible mix.

Option 1: Permissions only

You decide who may edit production and trust them. This is simple and fast. It works well in small teams where everybody knows everybody. It fails when a trusted person is tired, new or simply mistaken, because nothing else catches the error.

Option 2: Change requests

A second person reviews each guarded change, and the record is kept. This adds a few minutes to a change and removes many mistakes. It also provides evidence for audits.

Option 3: Settings kept in files and reviewed like code

Some teams keep their desired flag settings in files stored in a code repository, and apply them with a script. Every change is then a code change, reviewed in the team’s usual code review tool. This gives strong history and review, and fits teams who like working this way. It needs more effort to build, and changes made directly in the dashboard may fall out of step with the files.

Option 4: Formal change boards

Larger organisations may have a change advisory board that meets on a schedule to approve planned changes. This offers wide visibility but is slow, so it suits large, rare changes more than daily flag edits. Many companies now accept a lighter approval for flag changes, under the board’s general policy.

Option 5: Automation and guardrails

Monitoring tools can watch key numbers and automatically turn a feature off if errors rise. This does not replace review, but it adds a second line of defence after a change goes live.

A sensible mix

Many teams combine permissions, change requests in production, automatic guardrails on key metrics and a short written process. That mix keeps normal changes fast, makes risky ones safe and gives a clean record.

A process that has never been tried will surprise you at the worst moment. Rehearsal turns surprises into small, safe lessons.

Test the setup in a quiet environment

Before you rely on approvals in production, try them in a staging environment. Turn on the setting, create a request, approve it as a second user and publish. Look at the audit log. Try a scheduled change. This costs an hour and tells you exactly how your version behaves.

Test the emergency path

Pretend that a flag must be turned off urgently. Time how long it takes from the first alert to the live change. If it takes longer than the team is comfortable with, simplify the path: add approvers on call, pre-build kill switches or write clearer instructions.

Run a game day

A game day is a planned practice where a team pretends that something has gone wrong and works through the response. For flags, a game day might cover a bad flag change in production, a missed schedule or an approver who cannot be reached. The point is to learn about weak spots in a relaxed setting.

Retest after changes

After upgrading Flagsmith, changing plans, adding integrations or changing permissions, run the short happy-path test again. It takes minutes and catches surprises early.

What works for ten people may not work for two hundred. This chapter looks at growth and at the helpful automation that grows around change requests.

Many teams, many projects

Large companies usually give each product or major system its own Flagsmith project, with its own environments, permissions and approver groups. This keeps teams from reviewing things they know nothing about, and prevents one team’s rules from slowing another.

Approver groups that match ownership

Instead of one big list of reviewers, create groups that match who owns which areas: checkout, search, accounts, payments. Each group has several members so that holidays and illness do not stall work. Keep group membership in line with your company’s team lists.

Chat-based workflows

Teams often connect Flagsmith to their chat tool so that new requests appear in a channel, and reviewers can discuss them in the thread. Check which integrations your version offers. The goal is to bring the request to where people already are, not to build a second inbox.

Linking requests to tickets

Include the ticket number in the title or reason, so anyone can jump from the request to the plan and back. Some teams add rules in their ticketing tool that require a linked request before a ticket can be closed.

Bots that propose, humans that approve

A release pipeline can create a change request automatically after a successful deployment, for example to enable a flag for staff. The pipeline writes the description from the release notes. A human then reviews and approves. This keeps the speed of automation and the judgement of people.

flowchart LR
    CODE["Code merged and deployed"] --> BOT["Release pipeline"]
    BOT --> CRQ["Creates change request in Flagsmith"]
    CRQ --> CHAT["Posts to team chat channel"]
    CHAT --> REV["Reviewer opens and checks the request"]
    REV --> APR["Approves"]
    APR --> PUB["Publish or schedule"]
    PUB --> MON["Monitoring watches key numbers"]
    MON --> BOT

Measuring and improving

As you grow, keep an eye on three numbers: how long requests wait, how many are open and how often the emergency path is used. If waits grow, add reviewers or split projects. If emergency use grows, simplify the normal path. If open requests pile up, run a clean-up.

Culture beats configuration

The best setting in the world will not help if people see review as a chore to dodge. Teams where reviewers are thanked, where requests are short and clear, and where mistakes are discussed without blame tend to keep the process healthy for years.

Let us follow one flag change all the way from a thought in someone’s head to a different screen in a customer’s hand. Seeing the whole path helps you find where delays and mistakes can appear.

The full journey

flowchart TD
    IDEA["Idea or ticket"] --> DRAFT["Requester drafts the change"]
    DRAFT --> REQ["Change request stored as proposal"]
    REQ --> NOTE["Approvers notified by email or chat"]
    NOTE --> REVIEW["Review and questions"]
    REVIEW --> APPROVE["Approvals recorded"]
    APPROVE --> WAIT{"Scheduled?"}
    WAIT -- "No" --> PUBNOW["Publish now"]
    WAIT -- "Yes" --> HOLD["Hold until go-live time"]
    HOLD --> PUBNOW
    PUBNOW --> SWAP["Live state replaced in one step"]
    SWAP --> LOG["Audit log written"]
    SWAP --> REFRESH["Read caches refreshed"]
    REFRESH --> SDK["SDKs fetch new flags"]
    SDK --> USER["Customer sees new behaviour"]

Where time is spent

The last mile: how apps pick up changes

After a change is published, apps do not always notice at the same moment. Some apps ask Flagsmith for flags every time a page opens. Others keep a copy for a few minutes. Server programs using local evaluation download the whole environment and refresh it on a timer. Mobile apps may hold flags until they restart. This means that a change is not one instant but a short spread of moments.

What this means for planning

• Allow a few minutes of settling time before judging a change by the numbers.
• If two changes must happen together, design the app to cope when they arrive a little apart.
• For mobile apps, remember that very old versions may keep behaving as they did for days.
• For big launches, ask a person to test from outside your own office network, as a customer would.

What is recorded along the way

Every stage leaves a footprint. The request holds the story and the decisions. The approval records say who agreed. The audit log shows the exact change and its moment. Monitoring shows the effect. If you keep these four footprints together, you can reconstruct any change after the fact.

Real life produces situations that guides rarely mention. Here are common ones, with sensible ways to respond.

Scenario 1: A reviewer is on holiday

Scenario 2: A request is approved, but the plan changed

Scenario 3: Two teams want the same flag

Scenario 4: An approver is the requester’s manager

Scenario 5: The business wants a change this minute

Scenario 6: The audit asks for evidence

Scenario 7: A noisy week

Scenario 8: A request must be reversed

A short decision guide

Once the basics feel comfortable, a few deeper ideas decide how well change requests age as your company grows.

Feature versioning

Some versions of Flagsmith keep numbered versions of each flag’s settings in an environment. With versions, you can see earlier states, compare them and prepare a future state that goes live at a chosen time. Scheduling and approvals may rely on this option in some editions. Because behaviour differs by version, test how requests, versions and schedules work together in a staging environment before you build a launch plan around them.

Environment settings that matter to review

• The number of approvals. The heart of the process.
• Hiding sensitive values. Some environments can hide flag values from certain people. Reviewers need to see enough to judge a change, so decide who needs the view.
• Who can edit settings. The person who can change the approval rule is the real owner of the gate.
• Trait and identity handling. These affect how groups of users are matched, and therefore what a segment change really does.

Segments are shared, requests are not

A segment is defined at the project level and reused by every environment. A change request is about one environment. If someone edits the definition of a segment, they may change who is affected in all environments at once, even though the approval setting guards only one. Treat edits to segment definitions as sensitive, and decide in advance who may make them and who must review them.

Keeping flags healthy over time

Flags are not meant to live forever. A healthy flag moves through stages: created, tested, rolled out, fully on, removed from code, deleted. Old flags that nobody removes become clutter, and every request must then be reviewed against a long list of unfamiliar switches. Add flag removal to your normal definition of “done” for a feature.

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

Planning for people moving on

Every quarter, compare your approver groups with your real team lists. Remove people who have left, add new joiners who have been trained, and check that every group has at least three members. Assigning approvals to groups rather than individuals means that this regular tidy-up is quick.

Keeping documentation alive

Write your process in one short page: which environments are protected, how many approvals are needed, who the reviewers are, how to write a request, how to use the emergency path and whom to ask for help. Review the page whenever you change the setup. A page that is two years old is worse than no page, because people trust it.

Questions to ask yourself once a year

• Does approval still protect us from the mistakes that actually happen?
• Are we spending review effort where the risk is highest?
• Has any team found ways around the process, and why?
• Do new joiners understand the process within their first week?
• Would we be comfortable showing our records to an auditor tomorrow?

Review before change is an old idea in engineering. The descriptions below reflect what these organisations have discussed publicly, as patterns, not details of private systems.

GitHub and code review

The pull request, popularised by GitHub, is the best-known example of “propose, review, then merge”. Teams that already work this way find change requests natural: the same habits of describing, reviewing and approving apply to flag settings.

Google: change as the usual suspect

Google’s reliability writing emphasises that most outages follow some kind of change. Recording changes, reviewing risky ones and being able to roll back quickly are central habits. A flag change with a recorded reviewer fits that approach.

Netflix: gradual exposure

Netflix has talked about canary releases and gradual rollouts, where a change reaches a small share of traffic first and is compared with the old behaviour. Staged change requests, a small group first and then more, reflect the same careful path.

Facebook: gates for features

Facebook has described an internal gating system used to release features to employees first and then to growing parts of the public. Reviewing who sees what, and when, is part of that culture.

Amazon: two-person thinking

Large cloud and commerce companies commonly require a second person to look at risky operational changes, particularly for actions that could affect many customers at once. The reasoning is the same as in change requests: a single mistaken command should not reach everyone.

Banks and public bodies: change advisory boards

Banks, hospitals and government bodies often run formal change processes, where a group reviews planned changes and approves them for set windows. Change requests with scheduling are a light, faster version for flag settings, with a record that satisfies many of the same needs.

Experienced pilots do not trust memory for routine steps, and neither should you. Copy these into your team wiki.

Before you create a request

• Confirm the environment. Read its name twice.
• Check the list of open requests for the same flag.
• Decide whether this change really needs to be in production now.
• Write the reason, the check and the undo plan.
• Choose approvers who understand the system.
• Write the time and time zone for scheduled changes.

When you review a request

• Compare the proposed settings to the live ones, not to memory.
• Check the environment, the flag name and the value.
• Think about which users are affected and how many.
• Ask what happens if it goes wrong, and whether undo is easy.
• Check that the timing is safe: no sale, no other incident.
• Approve only when you would be comfortable defending the change.

Before you publish

• Check that the required approvals are in.
• Check that nobody has changed the flag since approval.
• Tell the people who need to know.
• Open the dashboards you will watch.

After you publish

• Check the live flag shows the new setting.
• Watch the dashboards for a few minutes.
• Record anything unusual.
• Close the request and clean up anything temporary.

Every quarter

• Review who can approve and who can change environment settings.
• Remove people who left or changed teams.
• Look at waiting times, old requests and emergency path use.
• Run an emergency drill.
• Retire flags that have finished their job.

A short reference for the words used in this guide.

Quick answers to the questions that come up most often.

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