Before learning any buttons, let us understand the problem that approvals solve.

One click, big effect

A feature flag is a switch that lives outside the program code. Flipping it can turn a new checkout page on, change a price, or hide a broken feature. It does not need a new release, so it happens in seconds. That speed is wonderful, and also risky.

The cost of a mistake

Imagine a tired engineer at the end of a long day. They mean to switch a flag in the Staging environment, but they are looking at Production. The switch is flipped, and customers see an unfinished page. The mistake took one second to make, and an hour to repair.

What a second pair of eyes gives you

• Catching slips. Wrong environment, wrong flag, wrong value.
• Sharing knowledge. The reviewer learns what is changing, and may know of a conflict.
• Timing advice. “Please wait until after the sale ends.”
• Accountability. Two people agreed, and both names are recorded.
• Calm. Teams who review feel safer, so they dare to release more often.

Four groups who benefit

A few Flagsmith words appear in every conversation about approvals. Let us make sure they are clear.

Organisation, project, environment

An organisation is your company account. It holds projects, usually one per product. Each project holds environments, such as Development, Staging and Production. Each environment has its own settings for every flag.

Feature and feature state

A feature is a named switch. A feature state is the setting of that feature in one environment: on or off, and possibly a value. Change requests protect feature states in the environments you choose.

Segments and overrides

A segment is a named group of users. An override gives that group, or one user, a special setting. Depending on your version, changes to these can also travel through the workflow.

People and roles

People log in as users. Users belong to groups and have roles or permissions that say what they may do. Approval is built on top of these permissions.

A change request is a proposal that waits for permission.

The simple definition

A change request is a saved proposal to change a flag. Instead of the flag changing at once, the new setting is stored as a draft. Reviewers look at the draft. Only after the required approvals is the draft applied to the real flag.

What a request holds

• A title, which says briefly what is proposed.
• A description, which gives the reason and any notes.
• The proposed settings: the new state and value.
• The requester, the person who made it.
• A list of chosen approvers, where the version supports it.
• The status: waiting, approved or published.
• Optionally a go-live time for scheduling.

What happens to the live flag meanwhile

Nothing. The real flag keeps its current setting while the request waits. Customers notice no difference until the request is published.

The workflow is the set of steps and rules that a request must pass through.

Request, review, approve, publish

In its simplest form, the workflow has four steps. Someone requests. Others review. Enough reviewers approve. Then someone publishes, which applies the change to the live flag.

The rules that shape it

• Where it applies. Usually only in sensitive environments such as Production.
• How many approvals. One, two or more, depending on risk and on what the version allows.
• Who may approve. Chosen people or groups, with the right permission.
• Who may publish. Often the requester, or anyone with the right permission.
• When it may go live. Immediately or at a scheduled time.

flowchart LR
    R["Request created"] --> V["Review by approvers"]
    V --> D{"Enough approvals?"}
    D -- "No" --> C["Changes asked or request closed"]
    D -- "Yes" --> P["Publish"]
    P --> L["Live flag updated"]
    L --> A["Audit log entry"]

Workflow is people plus rules

A tool can enforce counts and permissions. It cannot make a lazy reviewer careful. The best approval workflows combine good settings with a good habit: reading the request, asking questions and saying no when something looks wrong.

Every approval journey has a small cast. Knowing each role makes the whole story easy to follow.

The requester

The person who proposes the change. They write the title and reason, set the new value and choose approvers. A good requester makes it easy to say yes by giving clear information.

The approver

A person who reads the request and decides. They check that it is the right flag, the right environment, the right value and the right moment. They can approve, or decline to approve, and may add comments.

The publisher

The person who finally applies an approved request to the live flag. In many teams this is the requester. In stricter teams, it may be a release manager.

The administrator

The person who sets up the rules: which environments need approval, how many approvals are needed, and who may do what. Administrators should be few, and their own changes should be visible in the audit log.

The observer

Support staff, auditors or managers who only need to read requests and history. They cannot change anything.

Approvals are not on by default everywhere. They are a setting that administrators choose per environment.

Choosing where to require approval

Not every environment needs the same protection. Requiring approvals in Development would only slow people down. Requiring them in Production is wise for most teams.

The settings an administrator usually sees

• A switch to require change requests for the environment.
• A number for how many approvals are required, where the version allows.
• Choices about who may approve, based on users or groups.

What changes for people once it is on

After the switch, editing a flag in that environment no longer saves the change directly. The editor is guided to create a change request instead. This is a gentle but clear change of habit. Tell your team beforehand, explain why, and offer help in the first week.

Test first

Try the setting on a spare environment or a test project. Create a request, approve it with a second account and publish it. Seeing the real screens once prevents confusion later.

The quality of an approval depends on the quality of the request. A clear request is approved faster and more safely.

The title

Say what and where in a few words. “Enable checkout_v2 for 10 percent in Production” is clear. “Update flag” is not.

The description

Answer these questions in short sentences:

• Why? What problem or goal is behind the change?
• What exactly? Old setting, new setting, who is affected.
• When? Now, or at a chosen time, and why that time.
• How will we check? Which graphs or tests show success.
• How do we undo it? The simple way back.
• Link. The ticket or plan that explains the background.

The approvers

Choose people who understand the area. For a payment flag, include someone from the payments team. Do not pick a random colleague just because they are online.

A sample description

“We want to turn on the new checkout page for 10 percent of users in Production. Ticket 1234 has the test results. Staging has been on for a week without errors. If payment success drops below 97 percent, switch the flag off. Graphs are on the payments dashboard. Please approve before 10:00 so we can watch traffic during the busy hour.”

An approval is a promise: “I looked, and I agree.” Here is how to keep that promise honestly.

What an approver should check

How to say no kindly

If something looks wrong, do not approve. Write a short comment: what worries you and what would help. A good reviewer is a helpful colleague, not a gatekeeper who enjoys blocking.

The danger of rubber stamping

Rubber stamping means approving without reading. It happens when reviewers are busy, requests are huge or approvals feel like a formality. The result is the worst of both worlds: the delay of review, with none of the safety. If every request is approved in under ten seconds, ask whether anyone is truly reading.

Approval says “yes, you may”. Publishing is the act of actually doing it.

Two different steps

New users often think that approval and publishing are one thing. They are separate. An approved request still waits on the shelf until somebody publishes it. This gap is useful: it lets the team choose the best moment to go live.

What happens when you publish

• The system checks that the request is still valid and fully approved.
• The proposed settings replace the live settings for that feature state.
• An entry is written in the audit log.
• Caches are refreshed, so apps will see the new setting.
• The request is marked as published and closed.

One step, not many

The live flag is replaced in one action. Customers never see half of a change. This matters when a request changes several things at once, such as the state, the value and an override.

Who should publish

Two common patterns exist:

Watch after publishing

The work is not finished when the button is pressed. Watch the graphs for a few minutes. If something looks wrong, use the undo plan from the request.

More approvals mean more safety and more waiting. The skill is to match the number to the risk.

Think in risk levels

Not all flags are equal. A flag that changes the colour of a button is not like a flag that changes how payments are routed. Group your flags into levels and attach a rule to each level.

Different approvers for different reasons

• Technical approver. Checks that the change is correct and safe for the system.
• Business approver. Checks that timing and content fit the plan.
• Security or compliance approver. Checks sensitive or regulated changes.

Avoid approval chains that are too long

A request that needs five people will often wait for days. Reviewers assume that someone else is looking carefully. Two focused reviewers usually give better safety than five distracted ones.

Match the count to what the tool allows

Some versions let you set the number of required approvals per environment. Others offer simpler rules. If your version cannot enforce two approvals, you may agree a team rule, and check it in the weekly review of requests.

Sometimes the right moment is not now. Scheduling lets a request be approved today and applied later.

The idea

When creating a request, you can often choose a go-live time. The request then goes through approval as usual. When the time comes, the system applies it by itself. Nobody has to be awake at the keyboard.

Good uses

• A launch at a time announced to customers.
• A sale that starts at midnight local time.
• A change that must wait for a quiet traffic period.
• A temporary switch that should turn off after a campaign.

The risks of scheduling

• Stale approvals. The plan changes after approval, but the schedule stays.
• Nobody watching. The change happens while the team sleeps.
• Time zone mistakes. The change fires hours earlier or later than intended.

Safer scheduling habits

• Choose a go-live time when the right people are awake.
• Write the time with its zone in the description, using UTC as well as local time.
• Keep a shared list of scheduled changes for the coming week.
• Withdraw or update a request at once if the plan changes.
• Decide who will watch the graphs at the scheduled moment.

flowchart TD
    A["Request created with go-live time"] --> B["Approved"]
    B --> C["Waits for the scheduled time"]
    C --> D{"Plan still valid?"}
    D -- "Yes" --> E["Applied automatically"]
    D -- "No" --> F["Withdrawn or edited before the time"]
    E --> G["Audit entry and team watching"]

A request has a short life with clear stages. Knowing them helps you see where things get stuck.

The stages

stateDiagram-v2
    [*] --> Open: Requester creates
    Open --> Approved: Enough approvals
    Open --> Open: Edited after comments
    Open --> Closed: Withdrawn or declined
    Approved --> Published: Publish now or at schedule
    Approved --> Closed: Withdrawn before publishing
    Published --> [*]
    Closed --> [*]

Edits after comments

If an approver asks for a change, the requester edits the request. Depending on the version, editing may reset earlier approvals. This is a good thing: an approval given for an older version should not silently apply to a different new one.

Withdrawing

A requester who changes their mind should close the request, not leave it waiting. Old open requests clutter the list and may be approved by mistake months later.

The danger of old requests

An old approved request that nobody published can be dangerous. Its values may no longer fit the current state of the system. Review the list of open and approved requests every week, and close anything stale.

Teams are busy, and two people may want to change the same flag at the same time. Let us see what can go wrong, and how to stay safe.

The collision

Asha proposes to raise a limit from 100 to 200. Ravi proposes to switch the same flag off. Both requests are open. If Ravi’s is published first, then Asha’s request still describes a world in which the flag was on, and publishing it may switch it back on, undoing Ravi’s work.

Why this happens

A request describes a desired end state, built from what the flag looked like when the request was written. If the live flag changes in the meantime, the request is based on old information. Some versions detect this and warn you. Others rely on people noticing.

How to stay safe

• Before publishing, open the live flag and compare it with the request’s “before” values.
• Give every shared flag one clear owner, who coordinates requests.
• Announce in a team channel when you publish a Production change.
• Prefer small requests over big ones, so collisions touch less.
• If two requests overlap, combine them into one, or publish one and recheck the other.

sequenceDiagram
    participant A as Asha's request
    participant F as Live flag
    participant R as Ravi's request
    A->>F: Based on state S0
    R->>F: Based on state S0
    R->>F: Published first, state S1
    A->>F: Still based on S0
    Note over A,F: Publishing now could undo S1

What if a flag must be changed this minute, and the only approver is asleep? A workflow that cannot handle emergencies will be bypassed, which is worse.

The problem with rigid rules

When a feature breaks Production, minutes matter. If approving takes an hour, people will find side doors: shared accounts, administrator overrides, direct database edits. These side doors destroy the audit trail you worked so hard to build.

Design an emergency path on purpose

• Define “emergency”. For example, customer-facing outage, security issue or legal order.
• Name who may use it. A small group, such as the on-call engineers.
• Keep it fast but visible. One quick review by whoever is on call, or an approved way to bypass that still writes to the audit log.
• Review afterwards. Within a day, someone checks what was done and why.

Kill switches

Many teams create special flags whose only purpose is to turn something off quickly, such as “disable_recommendations”. Such a kill switch should be simple, tested and owned by on-call staff. Changes to it can follow a faster approval rule than ordinary flags.

Emergency is not an excuse

If every week someone declares an emergency to skip review, the path is being abused. Count emergency uses and talk about them openly.

A request that nobody notices will wait forever. Good communication is part of the workflow.

How approvers learn of a request

• Email. Flagsmith can notify chosen approvers by email in many versions.
• Chat messages. Through webhooks or integrations, a message can appear in a team channel.
• The dashboard. A list of open requests that approvers can check.
• Direct nudge. A friendly message from the requester, with the link.

What a good message says

“Please review: enable checkout_v2 for 10 percent in Production. Ticket 1234. Hoping to publish at 10:00 UTC.” It has the action, the place, the ticket and the time. A reviewer can decide in a few seconds whether they are the right person.

Response time agreements

Teams often agree on how fast reviews happen. For example, “Normal requests within four working hours. Urgent ones within thirty minutes.” Without such an agreement, requests wait in a silent queue and people grow frustrated.

Rotas for reviewers

If only one person can approve, a holiday stops the team. Use a rota, or a group of approvers, so someone is always available. Groups also remove the temptation to pick whoever answers fastest.

After publishing

Tell the team. A short chat message that says “published, graphs look fine” closes the loop for everyone who was waiting.

flowchart LR
    REQ["New request"] --> MAIL["Email to approvers"]
    REQ --> CHAT["Chat channel message"]
    REQ --> DASH["Open requests list"]
    MAIL --> REVIEW["Review and approve"]
    CHAT --> REVIEW
    DASH --> REVIEW
    REVIEW --> PUB["Publish"]
    PUB --> NOTE["Announcement after publishing"]

Flag changes are not only on and off. Reviewing richer changes needs a little extra care.

Percentage rollouts

A request may change a rollout from 10 percent to 50 percent. A reviewer should ask: has the 10 percent step been watched long enough? Are graphs healthy? Does the team have capacity for five times more traffic on the new path?

Segment overrides

If a request adds or changes a segment override, check the segment’s rules too. The segment itself may have been edited recently, and its edit may not be part of this request. Depending on version, segments might not go through the same approval path as flag states, so confirm how your setup treats them.

Order of overrides

The order of segment overrides decides which wins when a user belongs to several. A request that reorders them can change results for many users, even though no value changed. Reviewers should read the new order from the top and ask “who now wins?”

Multivariate values

For flags with several values, check that the percentages add up and that the default behaviour is safe.

Value content

If the flag carries text or configuration, read it carefully. A single wrong character in a configuration value can break an app. If the value is long, ask for a short explanation of what changed.

The workflow creates a paper trail without anyone writing it. That trail is what auditors and incident reviewers will read later.

What is recorded

• That a request was created, by whom and when.
• That it was approved, by whom and when.
• That it was published, by whom and when.
• The resulting change to the flag.

Two sources, one story

The request holds the reason and the comments. The audit log holds the facts and exact times. To answer “who authorised this and why?” you read both.

Evidence for auditors

An auditor may pick ten Production changes and ask for proof that each was approved. If your requests have clear titles and reasons, and your approvers are real people, this takes minutes. Keep exports of requests and log entries for the period the auditor needs, since the dashboard may not keep everything forever.

Be careful with the actor

The person who published may differ from the person who proposed. When you review history, open the request, not only the log line.

Let us look behind the screen. Understanding the parts explains why the workflow behaves as it does.

The big picture

flowchart TD
    UI["Dashboard and API"] --> AUTH["Authentication and permissions"]
    AUTH --> CR["Change request service"]
    CR --> STORE[("Database: requests and approvals")]
    CR --> RULES["Environment rules: approvals needed"]
    CR --> NOTIFY["Notifications and webhooks"]
    CR --> APPLY["Apply service"]
    APPLY --> STATE[("Live feature states")]
    APPLY --> AUDIT["Audit log"]
    APPLY --> CACHE["Serving caches"]
    CACHE --> SDK["Apps reading flags"]

The components in plain words

Why the live flag stays untouched until publishing

The request is stored in its own place, separate from live feature states. Customers read only live states. So reviewers can take as long as they like without changing anything customers see.

Reading is separate from writing

Apps ask for flags through a fast serving layer. Requests and approvals live on the administration side. The two sides meet only at the moment of publishing, when caches are refreshed. This design keeps flag serving quick, even when many requests are open.

Self-hosted notes

If you host Flagsmith yourself, requests, approvals and the audit log live in your database. Their safety depends on your backups, access control and upgrades. The hosted service handles these tasks within the terms of your plan.

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

sequenceDiagram
    participant Q as Requester
    participant S as Request service
    participant N as Notifications
    participant A as Approver
    participant L as Apply service
    participant C as Caches and apps
    Q->>S: Create request with title, reason, values
    S->>N: Notify approvers
    N->>A: Email or chat message
    A->>S: Read, comment, approve
    S->>S: Check approvals against environment rules
    Q->>L: Publish approved request
    L->>L: Replace live state in one step and write audit entry
    L->>C: Refresh caches
    C-->>Q: Customers see the new behaviour

Where the time goes

The last mile

After publishing, apps do not all notice at the same moment. Some ask Flagsmith for flags every time a page opens. Others keep a copy for several minutes. Server programs using local evaluation download the environment and refresh it on a timer. Mobile apps may hold flags until restart. A change is therefore not one instant, but a short spread of moments.

What to plan for

• Allow a few minutes of settling time before judging a change by the numbers.
• If two changes must happen together, make the app cope when they arrive slightly apart.
• For mobile apps, expect old versions to keep old behaviour for longer.
• For big launches, ask someone to check from outside your office network.

The workflow is only as strong as the permissions under it. Let us design roles that match how real teams work.

The principle of least privilege

Give each person only the rights they need for their job. Fewer rights mean fewer accidents and fewer possibilities for misuse. This principle is simple, and many teams still break it by making everyone an administrator “to save time”.

Four useful roles

Use groups, not individuals

Assign rights to groups such as “payments-reviewers”, then add people to the group. When someone joins or leaves a team, you change one membership, not dozens of settings. Groups also make it easy to answer the question “who can approve payment changes?” by listing one group.

Separate the duties

Where possible, the person who proposes a change should not be the only person who approves it. In regulated settings, the person who approves should also not be the person who publishes. This separation of duties reduces the damage that one mistaken or dishonest person can do.

Review access regularly

• Every quarter, list members of reviewer and administrator groups.
• Remove people who changed teams or left.
• Check that each group has at least two members, so holidays do not block work.

An approval workflow is a small production line for decisions. Like any line, it can clog. Let us see how to keep it flowing.

Cycle time

Cycle time is the time from creating a request to publishing it. If the average is a few hours, the workflow is healthy. If it is days, people will find ways around it, and flags will be changed outside the proper path or code will wait for approvals.

What causes queues

• Too few approvers, so a few people become a bottleneck.
• Requests that are too large, so reviewers postpone them.
• Poor descriptions, which cause long back-and-forth questions.
• No notifications, so requests are not seen.
• Too many approvals required for low-risk changes.

How to speed up without losing safety

• Use risk levels, with fewer approvals for low-risk flags.
• Use groups for approvers, so any member can answer.
• Provide a template for the description.
• Keep requests small and focused.
• Agree on response times, and show open requests on a team board.

Batching

If a launch involves many flags, it is tempting to bundle them all into one request. A single request that changes twenty things is hard to review. A better way is to group related flags into a few requests, each with a clear purpose, and a short overall plan that links them.

Watch the number of open requests

If open requests pile up, something is wrong. A healthy team has few open requests at any time, each recent.

An approval workflow is a security control. Like any lock, it must be protected from being picked.

Threats to think about

Multi-factor sign-in

Because an approval is a trust decision, the account that gives it must be well protected. Require multi-factor sign-in, or single sign-on with multi-factor, for anyone who can approve or publish in Production.

Machine keys and the workflow

Programs that call the Flagsmith administration API may be able to change flags without going through a human review, depending on key type and settings. Make sure you know which keys can change Production, who owns them and how their use is recorded. Limit them to what they must do.

Protect the rules

The most dangerous change is the one that removes the rule. If someone turns off approvals in Production, every later change loses its safety net. Make rule changes rare, restricted to a few administrators and visible through an alert.

Think about insiders

Most mistakes are honest, but some risks come from people inside. Separation of duties, audit trails and reviews of unusual activity protect honest staff as much as the company, since they show clearly what each person did.

Many rules and standards ask companies to prove that changes to live systems are authorised and traceable. A clear approval workflow is strong evidence. This chapter is general information, not legal advice, so your own advisers should confirm what applies to you.

The common requirement

Most standards ask three simple things: that changes are authorised before they happen, that they are traceable afterwards, and that the records are protected. Change requests answer the first. The audit log answers the second. Access control and exports answer the third.

Where flags fall under the rules

A flag that changes how payments are routed, how prices are shown or how personal data is handled is a change to a controlled system, even though no code was released. Security and service standards such as SOC 2 and ISO 27001 expect change management for such things. Financial reporting rules, for companies subject to them, expect control over systems that affect reported numbers. Privacy law such as GDPR expects care over how personal data is processed and logged. Sector rules in banking and healthcare add stricter expectations.

What auditors ask

Preparing for an audit

• Write a one-page description of your workflow.
• Export requests and audit entries for the whole period in question.
• Run your own sample every quarter, as practice.
• Check that leavers have lost their access.
• Be ready to explain every emergency change.

A workflow that nobody measures drifts. Simple numbers show whether it is healthy.

Metrics worth tracking

A rejection rate of zero is suspicious

If no request is ever questioned or sent back, either every proposer is perfect or reviewers are not reading. A modest rate of comments and reworks shows that people are actually looking.

Alerts

Start with a few. Alert when approvals are switched off or loosened in Production, when a permission group changes, and when someone publishes outside the usual path. Too many alerts teach people to ignore them.

The weekly walk-round

Once a week, one person looks at the list of open and approved requests, closes stale ones, and checks the week’s Production changes in the audit log. Ten minutes is enough.

Retrospectives

After an incident related to a flag, ask three questions: Did the workflow help or hinder? Was the reviewer given enough information? What small change would have caught it earlier? Write the answers down, and adjust the template or the rules.

Every process fails in predictable ways. Knowing them beforehand lets you respond calmly.

Scenario 1: The only approver is away

A request waits because the one person who understands the payments system is on holiday. Do not ask a stranger to click approve. Name a deputy in advance, and write short notes so a second person can learn the essentials. Treat a one-person group as a risk to be fixed.

Scenario 2: An approved request is stale

On Monday a request was approved. On Tuesday the plan changed. On Wednesday somebody publishes it. Customers see a half-ready feature. Fix: withdraw or update the request when plans change, and compare with the live flag before publishing.

Scenario 3: Two requests collide

One person’s publish undoes another’s. Fix: one owner per shared flag, announcements after publishing and a compare-with-live check.

Scenario 4: The rubber stamp

Approvals arrive in seconds and a mistake slips through. Fix: smaller requests, templates that make key facts visible, sampling of approvals in the weekly review, and a friendly culture that welcomes questions.

Scenario 5: The side door

People bypass the workflow with shared accounts or admin keys because it is too slow. Fix: an honest look at cycle time, a proper emergency path and removal of shared access.

Scenario 6: The workflow is turned off

Someone disables approvals in Production, perhaps “just for a moment”, and forgets. Fix: restrict rule changes, alert on them and review rules weekly.

Scenario 7: An emergency at night

A broken feature must be turned off while the approver sleeps. Fix: a defined emergency path, a kill switch owned by on-call staff and a review the next day.

Scenario 8: An approved scheduled change fires at a bad time

A launch was scheduled before a news event or a system outage. Fix: a shared list of scheduled changes, and a quick way to cancel.

Every control has benefits and costs. An honest comparison helps you choose how much workflow your team needs.

Trade-offs worth thinking about

Speed versus safety

Every approval costs time. Skipping approvals is fast, but leaves the audit log as your only protection, and a log can only tell you about a problem afterwards. The balance depends on the damage a mistake can do.

Strictness versus bypass

Very strict rules push people towards side doors. Rules that are strict where the risk is high and light where it is low are followed far more willingly.

Central control versus team freedom

One central group approving everything is safe in theory, but slow and ignorant of the details. Letting each owning team review its own flags is quicker and better informed, with central oversight only for the highest risks.

Detail versus readability

Requiring long descriptions improves quality, but long forms are skipped. A short template with five questions gives the best of both.

Teams that run approvals well tend to follow the same few patterns. Teams that struggle repeat the same few mistakes.

Good patterns

Anti-patterns

Here is a practical list of habits to adopt and traps to avoid.

Best practices

1. Require requests in Production only at first, and widen later if needed.
2. Use groups of approvers with at least two members each.
3. Write requests from a template with why, what, when, check and undo.
4. Keep requests small and focused.
5. Compare with the live flag before publishing.
6. Schedule at human hours and share a list of scheduled changes.
7. Agree on response times and watch cycle time.
8. Define an emergency path and review each use.
9. Protect accounts and rules with multi-factor sign-in and restricted rights.
10. Review roles quarterly and remove old access.

Common mistakes

Troubleshooting quick guide

• Cannot create a request. Your role may lack permission, or the environment may not require requests. Ask an administrator.
• Cannot approve. You may not be a listed approver, or you may be the requester. Check the rules.
• Cannot publish. The request may lack approvals, or you may not hold publishing rights.
• Approvals vanished after an edit. Your version may reset approvals on edit. Ask approvers to look again.
• Change did not appear for customers. Wait for caches and SDK refresh, then check the environment key and app settings.

Let us follow an imaginary company, “Acme Cart”, through a full launch to see all the ideas working together.

The situation

Acme Cart plans a holiday sale starting at 06:00 UTC on a Friday. The new “holiday_pricing” flag will show discounted prices. Prices are sensitive, so the team treats this as a high-risk flag in Production: it needs two approvals, one from the pricing team and one from the payments team.

Stage 1: Rehearsal in Staging

On Monday, an engineer, Asha, turns on the flag in Staging. Staging has no approval rule, so she changes it directly. She checks prices in the test shop, tries a percentage rollout and tests the undo step. The audit log shows her work.

Stage 2: Writing the request

On Wednesday, Asha creates a change request in Production with the title “Enable holiday_pricing for everyone at 06:00 UTC Friday”. Her description answers the template:

• Why: Holiday sale approved by the business, ticket 4521.
• What: Flag off to on, value “holiday_v1”, all users.
• When: Friday 06:00 UTC, which is 11:30 in Kolkata. Chosen because the team is online and traffic is low.
• Check: Prices on the product page, checkout total and payment success graph.
• Undo: Switch the flag off. Takes under one minute.

She selects approvers from the pricing group and the payments group, and sets the go-live time.

Stage 3: Review

Ravi from the pricing team reads the request, compares the values with the sale plan and approves. Meera from the payments team asks one question: “Have you tested the discount with the gift card payment type?” Asha replies that she has not. She tests it in Staging, finds a rounding error and fixes the flag value. She edits the request, so earlier approvals reset in this version. Both reviewers read it again and approve.

sequenceDiagram
    participant A as Asha
    participant R as Ravi (pricing)
    participant M as Meera (payments)
    participant F as Production flag
    A->>F: Create request, scheduled Friday 06:00 UTC
    R->>A: Approve
    M->>A: Question about gift cards
    A->>A: Test and fix in Staging
    A->>F: Edit request
    R->>F: Approve again
    M->>F: Approve
    Note over F: Waits for scheduled time
    F->>F: Friday 06:00 UTC applied and logged

Stage 4: Waiting and re-checking

On Thursday, a small outage in the pricing database delays another project. The team lead looks at the shared list of scheduled changes and asks: “Is the sale still safe to launch?” The pricing team confirms that the outage is fixed. The schedule stays.

Stage 5: Going live

At 05:55 UTC on Friday, Asha and Meera are online with the dashboards open. At 06:00 the flag turns on. Prices change. The payment success graph stays at 98 percent. Ten minutes later, Asha adds a note on the request: “Live at 06:00, graphs stable at 10 minutes.” The audit log has the full record.

Stage 6: Ending the sale

The team creates a second scheduled request to turn the flag off on Monday morning, with the same two approvers. After the sale, they remove the flag in a clean-up request, recorded in the log.

Tools enforce rules. People keep them alive. A small amount of written governance keeps an approval workflow healthy for years.

A one-page workflow policy

The policy should answer a few plain questions, and everyone should be able to find it in under a minute.

• Which environments require change requests?
• How many approvals are needed for each risk level?
• Who may approve, and who may publish?
• What is an emergency, and what is the emergency path?
• How fast do we respond to requests?
• Where are the records, and how long do we keep them?

Owners for each piece

Teach new people early

New teammates should learn four things in their first week: how to create a request, how to review one, where the emergency path is and where the policy lives. A short walk-through using a real past request is worth more than a long manual.

Naming rules help everyone

Clear flag names make reviews easier. “holiday_pricing_discount” tells a reviewer much more than “flag7”. Agree on a pattern and use it in all projects.

Regular reviews of the workflow

• Weekly: look at open requests, scheduled changes and the past week’s Production changes.
• Quarterly: review groups, roles, rules and metrics.
• After incidents: update the template and the rules.

When a company grows, one small workflow becomes many. New questions appear about consistency and speed.

Many projects, one standard

Large companies often have a Flagsmith project per product. Each project can have its own approval rules. Without a shared standard, one team may require two approvals while another requires none for the same level of risk. Agree on a company standard for risk levels, and let teams add stricter rules if they wish.

Cross-team approvals

Some flags touch several teams. A pricing flag might involve pricing, payments and legal. Name approvers from each team in the request, or choose a standing cross-team group for such flags.

Follow the sun

Teams in several time zones can hand over review duties. A request created in Kolkata in the afternoon can be reviewed by colleagues in London in the morning and published in the evening in San Francisco. This needs clear notes, time-zone-aware descriptions and shared groups that span regions.

Automation and the workflow

Pipelines that manage flags as configuration may create requests instead of applying changes directly, so that human review still happens for Production. A pipeline can fill in the template, link the ticket and tag the right approver group, saving time while keeping control.

Combining flags with release approvals

If your company already approves software releases, you can link both: the release approval covers the code, and the flag request covers the exposure. A short link between them in the description keeps the story together.

Measuring for improvement

Once you have request data, you can ask better questions. Which flags take longest to approve? Which teams get the most questions? Where do reworks come from? These answers help refine templates and training.

flowchart TD
    C["Company standard: risk levels and rules"] --> T1["Team A project rules"]
    C --> T2["Team B project rules"]
    C --> T3["Team C project rules"]
    T1 --> X["Cross-team approver group for shared flags"]
    T2 --> X
    T3 --> X
    X --> M["Shared metrics and reviews"]

A fire alarm is only useful if it rings. Test your workflow before you need it.

The first-time test

1. On a test project, create an environment that requires one approval.
2. Create a request with one account and try to approve it with the same account. See what happens.
3. Approve it with a second account.
4. Publish it and check the audit log entry.
5. Schedule another request for five minutes ahead and watch it apply.

The permission test

Use a test user with a low role. Check that the user cannot approve, cannot publish and cannot change environment rules. Then test a reviewer account and a release manager account the same way. The results should match your role design.

The emergency drill

Once a quarter, practise the emergency path in a safe setting. Who turns off a flag at three in the morning? How do they find the kill switch? Who reviews the use the next day? Time it.

The rubber stamp test

Take five recent approved requests and ask reviewers what they checked. If they cannot remember, the approvals may not be thorough. Adjust templates and sizes accordingly.

The notification test

Create a request and see how long it takes for approvers to notice. If nobody sees it for an hour, fix notifications.

Nobody builds a perfect workflow in a day. Here is a path with four levels, so you can see where you are and what comes next.

How to move up

Seeing the same request written three ways shows why details matter. Imagine the same change each time: turning on a new search ranking flag for a small share of users.

The weak version

Title: “Update search flag”. Description: “Please approve”. A reviewer reading this has no idea which flag, which environment or which users. They must either ask five questions or approve blindly. Both are bad outcomes.

The better version

Title: “Enable search_ranking_v2 for 5 percent in Production”. Description: “New ranking was tested in Staging for one week. We want to start with 5 percent of users.” This is already much clearer. The reviewer knows the flag, the place and the size of the step. But they still do not know how success is measured or how to go back.

The strong version

Title: “Enable search_ranking_v2 for 5 percent in Production, 10:00 UTC Thursday”. Description:

• Why: Product goal in ticket 3310, aiming for better search clicks.
• What: Flag off to on, percentage split 5 percent new ranking, 95 percent current.
• When: Thursday 10:00 UTC, when traffic is moderate and the search team is online.
• Check: Search click rate and error rate on the search dashboard, watched for thirty minutes.
• Undo: Set the split back to 0 percent, under one minute.
• Next step: If healthy for two days, request 25 percent.

Why the strong version is faster, not slower

It takes the requester two extra minutes to write. It saves the reviewer ten minutes of questions and prevents the back-and-forth that can add a day. Good requests are the cheapest speed-up a team can make.

Reading rules is one thing. Practising on examples is better. Here are three short review stories and what a careful reviewer would do.

Review 1: The wrong environment

A request is titled “Disable promo_banner”. The description says “Staging test finished”. But the request is in Production. A careful reviewer notices the mismatch between the story and the place. They ask: “The description mentions Staging, but this request is in Production. Do you want the banner off for real customers?” The requester realises the slip, closes the request and creates the correct one. A rubber-stamping reviewer would have switched off a live banner during a campaign.

Review 2: The rollout that jumps

A request changes a rollout from 5 percent to 100 percent. The description says “went well”. A careful reviewer checks the audit history: the flag has been at 5 percent for only twenty minutes. They reply: “Can we go to 25 percent first and watch for a few hours?” The requester agrees. At 25 percent, a small error appears in a rare browser. It is fixed before the whole audience sees it.

Review 3: The reorder with hidden effects

A request says “Minor tidy of overrides”. The new order places a broad segment above a narrow premium segment. A careful reviewer reads from the top and asks: “Who wins now when a user is both in the broad segment and premium?” They see that premium customers would lose their special setting. The request is changed before approval.

What the three stories share

• The reviewer compared the story with the actual change.
• They asked a specific, polite question.
• They thought about who is affected, not only what changed.
• They used history to understand the current state.

flowchart TD
    A["Open the request"] --> B{"Does the story match the change?"}
    B -- "No" --> Q1["Ask a clear question"]
    B -- "Yes" --> C{"Do I know who is affected?"}
    C -- "No" --> Q2["Ask or check segments and history"]
    C -- "Yes" --> D{"Are the check and undo plans clear?"}
    D -- "No" --> Q3["Ask for them"]
    D -- "Yes" --> E{"Is the timing sensible?"}
    E -- "No" --> Q4["Suggest another time"]
    E -- "Yes" --> OK["Approve"]

One size does not fit every team. A tiny start-up, a big bank and a game studio need different amounts of ceremony. Here is how to adapt.

A small start-up

Five engineers share one project. Everyone knows everyone. A heavy process would only slow them. A light setup works well: Production needs one approval from any other engineer, a short template and a chat message after publishing. Emergency changes are allowed, with a note in the channel.

A growing product company

Several teams share a project. Mistakes now affect more people. Introduce risk levels, approver groups per team and a weekly review of requests. Keep low-risk flags light, and require two approvals for payments and login.

A regulated business

Banks, insurers and healthcare companies must show control to auditors. Require two approvals for sensitive flags, separate approving from publishing, keep exports of requests and the audit log, and review access quarterly. Document everything, and test the emergency path.

A game or media studio

Live events, such as a weekend tournament, depend on exact timing. Use scheduled changes heavily, keep a shared calendar of events, and name the people who watch during go-live. Reviews focus on timing and load more than on money.

A platform team serving many teams

A central team owns Flagsmith for the whole company. They provide the standards, templates and training, while product teams own their flags and approvals. Central staff review only the highest risks.

Approval workflows are made of conversations. The way people speak to each other decides whether the workflow feels helpful or hostile.

Why tone matters

A request is a small act of trust: someone shows their work and asks for a check. If the reply sounds like an attack, the next person will hide details, or skip the process. If the reply sounds like help, people start to share earlier and more openly. Over months, this difference decides the culture of the whole team.

Useful ways to ask

• “Could you tell me how we will know if this works?”
• “I see this is in Production. Is that on purpose?”
• “What is the way back if the graphs look wrong?”
• “Who is affected by this segment?”
• “Would it be safer to start at a smaller share?”

Useful ways to decline

• “I cannot approve yet, because the undo plan is missing. Could you add it?”
• “The timing clashes with the sale. Could we move it to Thursday?”
• “I do not know this area well enough. Could someone from the payments team look too?”

Each reply says what the concern is and what would fix it. That keeps the request moving.

Useful ways to approve

A short note makes an approval more meaningful: “Checked flag, environment and values. Undo plan is clear. Approved.” This one line tells later readers that the reviewer looked, and what they looked at.

Things to avoid

• Sarcasm or blame, such as “Why would you do this?”
• Public shaming in a large channel when a private note will do.
• Long silent delays, followed by a rushed approval.
• Approving as a favour to a friend without reading.

Thanking catches

When a reviewer catches a real mistake, thank them publicly. When a requester fixes a mistake quickly, thank them too. Celebrating catches shows everyone that the process exists to help.

Keeping a catch log

Some teams keep a simple list of mistakes that reviews caught: the wrong environment, the missing undo plan, the unsafe jump in rollout. Reading the list every few months reminds everyone why the workflow exists, and gives new teammates real stories instead of abstract rules. It also shows where the template should ask better questions, so that the next mistake is caught even earlier.

Approval before action is an old idea. Almost every serious industry uses it. The descriptions below are general patterns that are widely discussed, not details of any private system.

Software code review

Most software teams require another engineer to review code before it merges. Platforms such as GitHub and GitLab have built approval rules directly into this process, with required reviewers, protected branches and recorded approvals. A flag change request is the same idea for behaviour changes that do not need new code.

Cloud infrastructure changes

Companies that manage infrastructure as code usually require review of infrastructure changes before they are applied, and often keep a separate step for the final apply. This mirrors the split between approval and publishing in Flagsmith.

Banking

Banks have long used a principle often called “four eyes”: important actions need two people. Large payments, changes to limits and changes to account settings often require a maker and a checker. Payment-related flags fit this model well.

Healthcare

Hospitals use double-checks for risky actions, such as certain medications. A second qualified person confirms the dose before it is given. The principle is the same, with a different level of stakes.

Aviation

Pilots use checklists with challenge and response. One person reads, another confirms. Aviation also shows the cost of a culture that blames: people hide mistakes. Open reviews help everyone learn.

Large technology companies

Companies that run products at huge scale have written publicly about reviewing configuration changes, staged rollouts and fast rollback. Their common message is that configuration changes can break products as badly as code changes, so they deserve review too.

Copy these into your team wiki. Short lists, used often, beat long manuals read once.

Before creating a request

• Rehearse the change in Staging.
• Check the environment name twice.
• Write a clear title with the flag and the place.
• Fill in why, what, when, check and undo.
• Link the ticket.
• Pick approvers who know the area.

When reviewing a request

• Confirm the right flag and the right environment.
• Compare old and new values line by line.
• Check timing against sales, releases and maintenance.
• Check the undo plan.
• Ask a question if anything is unclear.
• Approve only what you have read.

Before publishing

• Compare the request’s “before” values with the live flag.
• Confirm that plans have not changed since approval.
• Check that someone will be watching.
• Tell the team that you are about to publish.

After publishing

• Watch graphs for at least ten minutes.
• Add a note to the request with the result.
• Announce completion.
• Close related requests.

Every week and every quarter

• Close stale open requests.
• List scheduled changes for the next week.
• Review approver groups and roles.
• Check metrics and rule changes.
• Practise the emergency path.

A short reference for the words used in this guide.

Quick answers to the questions that come up most often.

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