1. What is a feature flag?
A feature flag (also called a feature toggle, feature switch, or release toggle) is a runtime control that changes application behavior without a new deployment. Instead of tying a release to a build, you place the new behavior behind a flag and ask the flag what to do:
flags.evaluate("checkout-v2", user) — the SDK sends the flag key and a user object, Maxlona checks your credentials, any active kill switch, and your targeting rules, then resolves a consistent per-user result so the same user keeps seeing the same variant as a rollout expands. Evaluation is fast enough to call on every request without noticeable latency.
Every Maxlona flag has one of three types — release (on/off rollout), experiment (comparing variants), or ops (kill switches, default "on") — and a separate configuration per environment, so the same flag key can answer differently in dev and production. If you want to see the reasoning behind a specific decision, call evaluation with ?explain=true or paste the flag key and a sample user into the JSON tester under Test → Tester — it returns the exact rule that matched. Full glossary: Core concepts.
2. Deployment ≠ release
Without flags, shipping code and exposing it to users are the same event: you deploy, and everyone gets the new behavior immediately. That couples technical risk (does the code work?) to business risk (should users see this yet?) into one moment. Flags split it into two independent decisions:
Engineering controls when code reaches an environment. It can sit there fully disabled while QA validates it.
Whoever owns the flag's configuration controls when — and for whom — it actually turns on.
That separation is what makes fast rollback possible: if a newly deployed flag causes trouble, you flip its configuration off in Maxlona instead of shipping a new build. It's also what turns a release from one large, all-or-nothing event into a measurable process — limit exposure, watch results, expand or stop.
3. Progressive delivery
Instead of flipping a flag to 100% at once, ramp exposure in stages — internal users, then testers, then 5%, 25%, 50%, everyone — validating performance, errors, and business results at each step. Maxlona gives you two first-class mechanisms for that, and one supporting pattern:
Turn a feature on for 10% of users, watch what happens, then move to 25%, 50%, 100%. The same user stays in the same bucket the whole way up, so nobody's experience flickers on and off as you ramp.
Skip randomness entirely and pick your audience by who they are — plan tier, region, account, or any attribute you send in. Save a rule once as a named segment (say, "Pro plan customers in the EU") and reuse it across every flag that needs it.
No test environment fully reproduces real traffic. Deploy the change, then point it only at internal staff or a handful of test accounts to validate against the real thing before anyone else sees it — no separate feature required, just the two above used deliberately.
4. Canary releases, dark launches & scheduled activation
These are patterns you build out of the primitives already covered, plus one genuine automatic-launch feature that's easy to miss.
Ship the code to production long before you're ready to talk about it. A release flag left off does exactly this — the feature is live and dormant, ready to switch on the moment you decide, with zero code deployed at launch time.
Maxlona's real auto-launch feature: give a flag a future go-live date and walk away. Nobody has to be online at 2am to flip it — the flag turns itself on the instant that time arrives, automatically, for every user it targets.
Try a change on a small slice of real traffic before betting the whole userbase on it — start a rollout at 1–5%, watch how it behaves, then decide to expand or pull it back. manual today you're the one watching the dashboard and moving the percentage — Maxlona doesn't yet auto-expand or auto-revert a canary based on live error rates for you.
Beta programs map onto real functionality the same way: target a beta-users segment instead of maintaining a separate application build.
5. Kill switches, circuit breakers & rollback
Picture a newly released integration that starts throwing errors in production. Without a runtime control, containing it means diagnosing the cause, writing a fix, getting it reviewed, building, deploying to every affected environment, and validating — all while the problem keeps running. A flag collapses that whole chain into one step: an authorized person turns the capability off, the application falls back to safe behavior immediately, and the team investigates without the pressure of live errors piling up in the meantime.
A dedicated emergency off switch for exactly this scenario. One person flips it, every affected user gets the safe default on their very next request, and there's a record of who did it and when — no code change, no build, no deploy.
The same idea applied preemptively: wrap a dependency you don't fully trust yet — a new payment provider, a recommendation service, an external API — in a flag before it ever causes trouble. If it misbehaves, you disable just that dependency and the application quietly falls back, instead of the failure cascading through your whole request path.
This isn't a substitute for reverting a genuinely broken deployment — some failures live in infrastructure or code that a flag can't reach. But for anything shipped behind a flag, "roll back" stops meaning "ship another build" and starts meaning "change a setting," which is the difference between a fix that takes minutes and one that takes a full release cycle.
Every activation is recorded with who did it and exactly when, so a post-incident review is reading a timeline instead of reconstructing one from memory and chat logs.
6. Continuous delivery & trunk-based development
Flags aren't a Maxlona feature so much as an enabler of two practices your team may already want: merging to a shared main branch continuously (instead of maintaining long-lived feature branches that rot into painful merges), and keeping the build always deployable because unfinished work stays hidden behind a flag that defaults off. Maxlona doesn't run your pipeline — it's the runtime layer your CI/CD hands off to after the build ships. See SDK libraries and Realtime updates for wiring flags into an existing pipeline.
7. A/B testing
An A/B test asks a different question than "does the new code work?" — it asks whether the new experience actually performs better. Create an experiment-type flag with two variants and a 50/50 split; users are assigned consistently by the same sticky-bucketing hash used for rollouts. Log conversions with a single call:
POST /experiments/events { flagId: "checkout-button-color", stage: "prod", eventName: "purchase", userId: "user-42", variantKey: "treatment" }
The Performance tab's A/B Experiments card runs a two-proportion z-test of each variant against control and surfaces a p-value, relative uplift, and a winner badge once a result crosses the 95% confidence threshold. Full reference: A/B testing.
8. Feature gating by plan or audience
Gating a capability to Basic / Standard / Enterprise plans, early-access partners, or internal tools isn't a separate primitive in Maxlona — it's the same targeting rule and segment system from section 3, pointed at a plan attribute you pass in on the user object at evaluation time. There's no built-in billing/subscription integration that auto-syncs plan tiers — your application supplies that attribute.
One caution worth repeating from the original guidance: feature gating controls whether a capability appears, not who's authorized to use protected data or privileged operations. Don't use a flag as a substitute for real authorization — pair it with your own access-control layer.
9. Environments & applications
Every flag configuration is scoped to an environment (dev, staging, production, or whatever stages you define) and, optionally, a single application — so checkout-v2 can be fully enabled in staging while sitting disabled in production until release approval clears it. Evaluation and Management Keys can themselves be pinned to one application and narrowed to one environment, which is what keeps a staging key from ever touching production data.
Not every environment fits every flag. By default a new environment appears on all flags, but you can make it opt-in so it only appears on the flags that add it — useful for a partner sandbox or a regional stage that only a few applications deploy to. Each flag can also drop a default environment it never ships to. Both choices live on the flag's Manage environments dialog. Removing an environment from a flag deletes that flag's configuration there, so it must be switched off first; SDKs evaluating the flag in that environment receive its fallback value.
Environments and dependencies. A dependency is checked in the environment being evaluated, so a parent flag must be in every environment of the flag that depends on it. A parent may have extra environments. If it is missing one, the dependent flag would always be off there, so Maxlona won't let that happen silently: you can't add a dependency on a parent that is missing one of the flag's environments. When a change in Manage environments would create a mismatch, the dialog shows exactly which flags are affected and lets you choose. Line up the environments adds the environment to the parent flags, or removes it from the dependent flags (which must be off there). Remove the dependency keeps your change and removes the dependency in every environment, with its own audit entry. Making an environment opt-in is refused while it would create a mismatch, and names the flags to fix first.
10. Feature flag lifecycle
A flag should move through a defined lifecycle, not just get created and forgotten. Here's the standard nine-stage model, with what Maxlona actively tools for you and what's still a manual habit:
| Stage | What happens | Maxlona support |
|---|---|---|
| 1–2. Plan & create | Pick a descriptive key, initial state, environments, targeting. | ships today |
| 3–4. Implement & deploy | Integrate the SDK call, define the safe default, ship with production disabled. | ships today |
| 5–6. Validate & roll out | Enable for internal/limited audiences, then ramp via percentage or segment. | ships today |
| 7. Monitor | Watch the rollout's effect before expanding further. | audit + webhooks |
| 8. Complete | Reach 100% and hold. | ships today |
| 9. Retire | Delete the flag and the old code path once it's no longer earning its keep. | not built in — manual |
11. Naming, flag debt & safe defaults
Stage 9 is the one Maxlona doesn't automate, which makes the habits below the difference between a clean flag list and a graveyard of dead conditionals:
- Name flags for the behavior they gate, not the ticket that created them — enable-new-checkout, not flag-1234 or temp.
- Decide the safe default — what the application does if evaluation fails or Maxlona is briefly unreachable — before wiring the flag into code. For most release flags, disabled is safest; for an ops flag guarding a dependency, the current stable path usually is.
- Give every temporary flag an owner, and record whether it's meant to be temporary or permanent when you create it — nothing in the product enforces this, so it has to be a team convention.
- Set a per-flag stale period in the Automation planner. Maxlona tracks how long a release remains fully released, notifies the team when it becomes stale, and archives only when an explicit archive time passes its safety checks.
- Watch for the classic failure modes: testing only the enabled path, using a flag as a stand-in for authorization, deeply nested flag conditions, and editing production flags outside the approval workflow when one is configured.
12. Flags vs. configuration, and why runtime control matters
Application configuration (connection strings, log levels, endpoints) describes how something runs. A feature flag decides whether a behavior runs and for whom. The overlap — and the reason flags are worth a dedicated system instead of another config file — is that a flag change takes effect immediately for the right audience without editing files, restarting services, or rebuilding and redeploying the application. That's the entire value proposition of runtime evaluation.
13. Flags for AI systems
Routing between AI model versions, prompts, or providers is a legitimate use of a feature flag — If UseNewAIModel is enabled: route eligible requests to the new model — and it works today because it's just a targeting rule and a percentage rollout applied to that decision.
not built in there's no AI-specific tooling — no built-in latency/quality/cost dashboards for model comparisons. You'd wire that up with your own observability, using Maxlona purely for the routing decision.
14. Access, audit & monitoring a release
Runtime controls affect production, so who can touch what should be explicit rather than assumed.
A viewer can look but not touch anything. An editor can change flags and rollouts. An admin also manages members, approvals, and credentials. Nobody gets more reach than their job needs by default.
A key issued for your checkout service's production environment can't be reused to read or write flags for a different application or environment, even by accident.
Review available change records to see who changed a flag and compare recorded values before and after the change.
Mark production as approval-required and a change there waits for a sign-off before it takes effect, instead of going live the moment someone clicks save.
For watching a rollout's effect in real time, subscribe to webhooks or the streaming connection for change events. not built in beyond A/B experiment significance results, Maxlona doesn't ship a general business-metrics dashboard (conversion, revenue, engagement) — pair flag change events with your own analytics/APM to close that loop.
15. A full release walkthrough
Putting it together — shipping a redesigned checkout button end to end:
- Create an experiment flag checkout-button-color from the Gradual Percentage Rollout template, disabled in production.
- Deploy the code behind flags.evaluate("checkout-button-color", user) — engineering ships it while it's still off for everyone.
- Enable it for internal users in staging; QA checks both variants using the JSON tester.
- Turn it on for 10% of production traffic. Each conversion fires POST /experiments/events.
- If production requires approval, this change sits as a pending approval until an admin reviews the diff and approves it — the audit log and a webhook fire the moment it does.
- Watch the A/B Experiments card for a winner badge; if the treatment underperforms, flip the flag off — no redeploy needed.
- Once the winning variant holds at 100%, retire the flag and delete the losing code path. This last step is on you — see section 11.
16. Use cases
Everything above is a set of primitives. Here's where teams actually reach for them, and which primitive each scenario is built from. For three fully worked, end-to-end examples, see the dedicated Use cases page →
Deploy it dark, turn it on for your own team first, then ramp 10% → 50% → 100% while you watch. If something's wrong, it's wrong for a slice of users, not all of them.
Wrap a new payment provider or third-party API in an ops flag before it ever ships. If it misbehaves in production, you cut it off in seconds instead of writing an emergency hotfix.
Run the old and new code paths side by side behind a flag, move traffic gradually, and if the new path has a problem, "rollback" means flipping a setting — not reverting a deploy under pressure.
Target a "beta-users" segment instead of maintaining a separate build or branch. Add or remove someone from the program by editing the segment, not by redeploying anything.
Basic, Standard, and Enterprise customers hit the same code — a targeting rule on the plan attribute decides who actually sees the capability.
Send a percentage of requests to a new model or prompt version, compare it against the incumbent using your own metrics, then ramp or roll back the same way you would any other flag.
17. The Maxlona approach
Maxlona treats a feature flag as one object that travels a full lifecycle — create, activate, roll out, fully release, detect staleness, schedule removal, and archive — with environment-scoped configuration, role-gated access, safety checks, and an audit trail at every step. Retirement remains deliberate: stale detection can notify automatically, while archival requires an explicit scheduled action and is blocked by active dependencies.
The core principle underneath all of it: deploying code and releasing functionality are different decisions. Your CI/CD pipeline decides when code reaches production. Maxlona decides when that functionality actually turns on, and for whom.